121 lines
5.6 KiB
Markdown
121 lines
5.6 KiB
Markdown
## 开发日志上下文注入
|
||
|
||
每次会话处理用户第一个任务前，执行以下操作：
|
||
|
||
1. 读取 `.claude/changelog/changelog-headlines.md`（不存在则跳过）
|
||
2. 如文件存在且有实质内容（不仅是模板头部），将全部条目作为背景知识注入上下文
|
||
3. 这些信息帮助 Agent 快速建立位置感：项目进展到什么阶段、最近的工作重心在哪个模块
|
||
4. 在后续回复中自然参考，不显式提及"根据开发日志"
|
||
|
||
## 主动定位辅助
|
||
|
||
L3 概要的核心价值之一是帮助 Agent 在**冷启动**（新会话、无上下文）时理解用户意图。
|
||
当用户的请求缺少具体文件名或模块名时，Agent 应主动利用 L3 进行推断：
|
||
|
||
### 典型场景
|
||
|
||
1. **隐式延续**：用户说"继续做昨天那个"、"把那个功能完善一下"
|
||
→ 从 L3 中找到最近的相关条目，上溯到 L2 获取具体文件列表
|
||
2. **模糊指代**：用户说"那个组件有 bug"、"之前改的那个接口"
|
||
→ 用 L3 中的关键词匹配用户描述，定位到具体改动
|
||
3. **上下文补全**：用户直接提出一个任务，没有背景说明
|
||
→ 用 L3 判断该任务是否与近期某个改动有关联（如同一模块、同一功能线）
|
||
|
||
### 流程
|
||
|
||
```
|
||
1. 解析用户请求，识别是否存在隐式引用或模糊指代
|
||
2. 在 L3 概要中查找语义最匹配的 1-3 条记录
|
||
3. 提取匹配条目的锚点 ID，上溯到 L2 获取 affected_files 和 tags
|
||
4. 如有必要，继续上溯到 L1 获取完整的决策背景
|
||
5. 将定位到的文件/模块作为任务的起点，开始执行
|
||
```
|
||
|
||
如果 L3 中没有匹配到任何相关记录，正常处理即可——不是所有任务都与近期改动有关。
|
||
|
||
## L2 自动触发
|
||
|
||
Agent 开始处理一个新任务时，判断是否需要读取近期详细记录：
|
||
|
||
1. 从当前任务中提取涉及的文件路径和语义关键词
|
||
2. 与 L3 概要中的内容做快速比对——如果近期有相关模块/文件的改动记录
|
||
3. 命中时，读取 `.claude/changelog/changelog-recent.md`，将相关条目纳入上下文
|
||
4. 匹配策略：
|
||
- 硬匹配：当前任务涉及的文件出现在 L2 条目的 `affected_files` 中
|
||
- 软匹配：当前任务的语义关键词与条目的 `tags` 有交集
|
||
- 任一命中即触发读取
|
||
|
||
### 注意
|
||
|
||
- L3 注入是低成本操作（~50 句话），每次会话都执行
|
||
- L2 读取按需触发，只在检测到关联时才读取
|
||
- 开发日志是事实性记录，直接使用即可，不像画像那样需要"自然融入"的措辞考量
|
||
- 记录的写入和管理由 `dev-changelog` Skill 负责，本 Rule 只负责读取和注入
|
||
|
||
## 逐级上溯
|
||
|
||
当 L3 中某条记录的一句话描述**语义模糊**（无法判断具体范围或与当前任务的关系），
|
||
按以下步骤精准上溯，**禁止全文读取 L1**：
|
||
|
||
1. 提取该条目的锚点 ID（`CL-xxx`）
|
||
2. 用 Grep 在 `changelog-recent.md`（L2）中搜索该 ID → 找到则读取该条目
|
||
3. 如 L2 中未找到或仍有歧义 → 用 Grep 在 `changelog-full.md`（L1）中搜索该 ID，
|
||
获取行号后用 Read 工具读取该行号 ±20 行范围
|
||
4. 一次上溯通常只涉及 1-3 条记录，不批量上溯
|
||
|
||
## 任务完成 Checklist（强制）
|
||
|
||
Agent 在即将输出最终回复前，**必须**逐项检查以下清单。
|
||
这是硬性要求，不是建议——**跳过任何一项都视为执行错误**。
|
||
|
||
### 前置项（每次回复前无条件执行）
|
||
|
||
**A. 画像信号扫描（短路版）**
|
||
|
||
目的：以最小 token 成本维持 `profile-memory` Skill 的被动检测通路。
|
||
|
||
步骤：
|
||
|
||
1. **快判（词表匹配）**：扫描本次对话中**用户消息**，检查是否**明显**出现以下偏好/决策触发词族之一：
|
||
|
||
- 个人偏好信号：`我喜欢` / `我倾向` / `我不喜欢` / `我讨厌` / `以后都` / `以后别` /
|
||
`别再` / `不要再` / `我的风格` / `我的偏好` / `太花哨` / `minimal` /
|
||
`简洁` / `精炼` / `啰嗦`
|
||
- 项目决策信号：`这个项目是` / `目标用户是` / `技术栈` / `架构上` /
|
||
`产品方向` / `定位是`
|
||
|
||
2. **分支**：
|
||
- 无匹配 → **直接跳过**，进入下一 checklist 项（thinking 应在 50 token 内结束）
|
||
- 有匹配 → 读取 `.claude/skills/profile-memory/SKILL.md` 并执行操作 A 的确认流程
|
||
|
||
3. **约束**：本项不做全量语义判断——漏记隐式信号是可接受的权衡。
|
||
用户如需记录隐式偏好可显式说"把这条记入画像"。
|
||
|
||
### 变更检查项（仅当本次有代码/配置文件改动时执行）
|
||
|
||
1. **本次是否有代码/配置文件改动？**（不含 `.claude/` 下的基础设施文件）
|
||
- 否 → 跳过本组后续项，直接进入"收尾项"
|
||
- 是 → 继续
|
||
|
||
2. **是否已写入三层开发日志？**
|
||
- 否 → **立即**读取 `dev-changelog` Skill 并执行操作 A，写入 L1 + L2 + L3 后再输出回复
|
||
- 是 → 继续
|
||
|
||
3. **是否修改了任何 Skill？**（包括 SKILL.md 内容变更）
|
||
- 否 → 跳过
|
||
- 是 → 检查是否已同步 `epee-orchestrator` 的 `registry.md`，未同步则立即执行
|
||
|
||
4. **本次是否有 Skill 使用异常？**（遗漏、误触、产物与用户预期偏差）
|
||
- 否 → 跳过
|
||
- 是 → 执行 `epee-orchestrator.md` 中的自迭代确认流程
|
||
|
||
### 收尾项（每次回复前无条件执行）
|
||
|
||
**Z. 静默 Hook ack**
|
||
|
||
- 用 Write 工具创建空文件 `.claude/changelog/.changelog-ack`
|
||
- 这会更新 ack 文件的 mtime，阻止 `check-changelog` hook 在后续回复中重复提醒
|
||
|
||
**执行原则**：先完成 checklist 中的所有写入动作，再输出面向用户的回复文本。
|
||
回复末尾如果执行了变更检查项第 2 项，附 `[已记录到开发日志]`。
|