398 lines
18 KiB
Markdown
398 lines
18 KiB
Markdown
# AGENT_RULES
|
||
|
||
目的：为本仓库提供稳定的 Matt Pocock 工程流程与 ticket 执行约束。
|
||
|
||
`.scratch/` 是 spec、ticket、feature 队列和执行状态的唯一事实源。
|
||
`memory-bank/` 保存稳定的项目定位、技术上下文和当前系统模式。
|
||
`CONTEXT.md` 保存稳定领域词汇，`docs/adr/` 保存关键架构决策。
|
||
|
||
## 优先级
|
||
|
||
1. 系统/开发者指令
|
||
2. 项目私有规则：`AGENT_RULES.local.md`（如存在）
|
||
3. 仓库规则：`.agents/` 与 `AGENTS.md`
|
||
4. 本文件
|
||
|
||
## 沟通原则
|
||
|
||
- 统一使用简体中文
|
||
- 发现用户理解有误时，礼貌纠正
|
||
- 不给时间估算，专注事实、风险与下一步
|
||
|
||
## 项目边界
|
||
|
||
- `{{PLAYBOOK_ROOT}}/` 是 Playbook 模板/供应商目录，不是业务项目源码
|
||
- 除非任务明确维护 Playbook，不得修改 `{{PLAYBOOK_ROOT}}/` 下内容
|
||
- 当前项目的生效规则位于项目根目录的 `AGENT_RULES.md`、
|
||
`AGENT_RULES.local.md`、`AGENTS.md` 与 `.agents/`
|
||
- 搜索、批量修改、review 和提交时默认排除 `{{PLAYBOOK_ROOT}}/`
|
||
- 不覆盖、stash、reset 或提交不属于当前 ticket 的既有改动
|
||
|
||
## 会话启动
|
||
|
||
处理首个实质性任务前，按相关性读取；不存在则跳过：
|
||
|
||
1. `AGENT_RULES.local.md`
|
||
2. `.agents/index.md`
|
||
3. `memory-bank/project-brief.md`
|
||
4. `memory-bank/tech-context.md`
|
||
5. `memory-bank/system-patterns.md`
|
||
6. `docs/agents/issue-tracker.md`
|
||
7. `docs/agents/domain.md`
|
||
8. `CONTEXT.md` 或 `CONTEXT-MAP.md`
|
||
9. 相关 `docs/adr/`
|
||
10. `main_loop.py status --state-root .scratch` 的当前状态
|
||
|
||
## 任务入口
|
||
|
||
### 可直接执行
|
||
|
||
只读分析、定位、审查，以及不改变行为的局部机械修改可以直接执行，不生成
|
||
spec/tickets。仍须遵守项目规则、验证实际结果，并只处理本次相关改动。
|
||
|
||
### 新 feature 或设计变更
|
||
|
||
需要需求澄清、设计取舍、跨 session 调度、并发执行、迁移或回滚时，进入完整工程
|
||
主链。边界不清时也走该入口；执行中才发现存在未确认设计时停止实现，已有改动只作为
|
||
事实输入，不视为已批准方案。
|
||
|
||
### 已明确预期行为的 bug
|
||
|
||
已知正确行为且可以建立失败反馈回路的 bug，使用 `diagnosing-bugs` 完整执行 Phase 1-6，
|
||
由它负责反馈回路、回归测试、修复、验证和清理，不再进入 `implement` 或重复 `tdd`，也不为
|
||
已确定的需求重新 grilling。若诊断暴露新的产品取舍、架构方向或缺失测试 seam，停止修复并
|
||
转入 `grill-with-docs`。若 bug 来自已领取 ticket，Phase 6 后直接继续本地 ticket 执行协议的
|
||
提交、review 和 finish 门禁。
|
||
|
||
## 正式工程主链
|
||
|
||
新 feature 或设计变更使用以下顺序：
|
||
|
||
```text
|
||
setup-matt-pocock-skills
|
||
-> grill-with-docs (grilling + domain-modeling)
|
||
-> to-spec
|
||
-> to-tickets
|
||
-> main_loop.py enqueue
|
||
-> main_loop.py claim
|
||
-> 本地 ticket 执行协议 (tdd -> commit -> code-review -> finish)
|
||
-> main_loop.py integrate
|
||
```
|
||
|
||
- 每个仓库首次使用时运行 `setup-matt-pocock-skills`，本地开发选择 local markdown tracker
|
||
- 正式仓库设计使用 `grill-with-docs`
|
||
- 进入 `grill-with-docs` 或本地 ticket 执行协议前，重新读取 `memory-bank/project-brief.md`、
|
||
`memory-bank/tech-context.md` 和 `memory-bank/system-patterns.md`
|
||
- `grilling` 必须走完整 design tree，frontier 清空并经用户确认后才进入 `to-spec`
|
||
- `to-spec` 不重新进行已经完成的需求采访；但必须按其原始流程确认测试 seam。若
|
||
grilling 尚未确认 seam，必须先向用户完成 seam confirmation
|
||
- `tdd` 不得在未经确认的 seam 上开始
|
||
- `to-tickets` 产出可独立验证的 tracer-bullet tickets，并显式声明 `Blocked by`
|
||
- 一次可以先生成多个 feature 的 spec/tickets，再按期望顺序逐个 `enqueue`
|
||
|
||
## On-ramps 与 detours
|
||
|
||
- 超过单个 session 可容纳的巨大、模糊工作先走 `wayfinder`；决策地图清晰后进入
|
||
`to-spec -> to-tickets`，不得从决策 ticket 直接跳到实现
|
||
- `research` 产出的高可信一手来源报告先进入 `grill-with-docs`，作为设计输入；调研不能
|
||
替代 grilling
|
||
- 已由 `to-tickets` 生成的 ticket 直接从 `main_loop.py claim -> 本地 ticket 执行协议` 开始，
|
||
不再 triage 或重复需求采访
|
||
|
||
## Phase boundaries
|
||
|
||
只在阶段边界按以下顺序判断，首个满足项生效：
|
||
|
||
1. 下一阶段需要当前 primary source 且 smart zone 足够时，继续当前 session
|
||
2. 当前上下文与下一阶段无关时，使用 `clear`
|
||
3. 仅在跨 harness、跨目录/仓库、交给同事或 mid-phase 分出旁支任务时使用 `handoff`
|
||
4. 任务可独立 AFK 完成时交给 subagent
|
||
5. 其余同 harness、同目录且仍需当前上下文的情况使用 `compact`
|
||
|
||
上下文过长不等于必须 `handoff`；`handoff` 解决的是可移植性。`compact` 是决策树的默认
|
||
落点，但不是第一选择。`CONTEXT.md` 和 memory-bank 都不能替代阶段上下文。
|
||
|
||
## 本地 Ticket 执行协议
|
||
|
||
这是 Playbook 对 Matt 工程 skills 的调度适配层。它复用 `tdd` 和 `code-review`。
|
||
不直接调用上游 `implement`；后者的 `code-review -> commit` 尾部顺序无法生成主循环要求的
|
||
固定 commit 证据。
|
||
|
||
对每个 claim 严格按以下顺序执行：
|
||
|
||
1. 读取已领取 ticket 的 spec、ticket、相关稳定知识和 ADR
|
||
2. 在已确认 seam 上按 `tdd` 完成 ticket 的可观察行为，并运行局部验证
|
||
3. 提交全部实现，使 ticket branch `HEAD` 成为固定、干净的审查点
|
||
4. 运行 `code-review`，显式提供 fixed point 和 Review 适配契约规定的需求来源
|
||
5. 修复硬 finding 后重新提交、验证和 review，直到两个 axis 均满足 pass 条件
|
||
6. 调用 `main_loop.py finish`，提交与当前 `HEAD`/base 绑定的结构化证据
|
||
|
||
## 文档职责
|
||
|
||
- `memory-bank/project-brief.md`：稳定项目定位、边界、目标和成功定义
|
||
- `memory-bank/tech-context.md`：技术栈、工具链、环境差异和验证入口
|
||
- `memory-bank/system-patterns.md`：当前模块边界、数据流、系统不变量和扩展路径
|
||
- `CONTEXT.md`：稳定领域词汇和定义，不记录 feature 状态
|
||
- `docs/adr/`：难以逆转且需要长期背景的真实技术取舍
|
||
- `.scratch/<feature>/spec.md`：单个 feature 的问题、方案、用户故事和测试决策
|
||
- `.scratch/<feature>/issues/*.md`：ticket DAG、验收标准和机器状态
|
||
- `.scratch/queue.md`：feature 开发与集成顺序
|
||
- `docs/agents/*.md`：tracker、领域文档布局和 skill 配置
|
||
|
||
不得手工修改 ticket 的 `Status` 或 `main-loop:ticket-state` 区块；只通过主循环变更。
|
||
|
||
## 稳定知识维护
|
||
|
||
只记录下一 session 仍需要的稳定知识；当前 feature、ticket、owner、heartbeat、验证和
|
||
集成状态只由 `.scratch/` 与 `main_loop.py` 维护。
|
||
|
||
- 项目定位、边界、目标或成功定义长期变化时，更新 `project-brief.md`
|
||
- 技术栈、工具链、环境差异或验证入口长期变化时，更新 `tech-context.md`；写入
|
||
`tech-context.md` 的命令和环境事实必须已经验证
|
||
- `system-patterns.md` 记录当前成立的架构；关键取舍及理由写入 `docs/adr/`
|
||
- `CONTEXT.md` 只记录稳定领域词汇和定义；不把聊天流水、未验证猜测或短期进度写入
|
||
`CONTEXT.md`
|
||
- 项目特有执行规则写入 `AGENT_RULES.local.md`
|
||
- 符合 phase-boundary 窄条件的可移植上下文由 `handoff` 写入 OS 临时目录，不写入稳定
|
||
知识文件；同 harness、同目录的续作优先按决策树选择 continue、clear 或 compact
|
||
- 不为普通实现选择创建 ADR；没有长期价值的信息时不更新这些文件
|
||
|
||
## 调度语义
|
||
|
||
- feature 按 `.scratch/queue.md` 顺序调度
|
||
- 同一 feature 中 blocker 全部满足的 tickets 构成 frontier，按稳定编号领取
|
||
- 同一 feature 的多个 frontier tickets 可在 worktree 模式并发执行
|
||
- 当前 feature 的 frontier 全被领取时返回 `BUSY`，不向后续 feature 扩张
|
||
- 只有前序 feature 无 frontier、无活动 claim 且确实 blocked 时，才可开发后序 feature
|
||
- 前序 feature 恢复后，新 claim 重新优先前序 feature
|
||
- 后序已领取 ticket 可以完成，但 feature 集成到 `main` 必须严格遵循队列顺序
|
||
- `resolved` 和显式 `skipped` 满足 blocker；`claimed`、`blocked`、
|
||
`ready-for-agent` 不满足
|
||
- 含 `skipped` ticket 的 feature 标记为 partial，集成时必须显式授权
|
||
- stale 只由 heartbeat 时间派生，不自动转移 owner；只有 `reclaim` 可以接管
|
||
|
||
## 执行隔离
|
||
|
||
`claim --isolation` 支持：
|
||
|
||
- `in-place`：串行执行，不创建额外 worktree；claim 生命周期内其他 owner 得到 `BUSY`
|
||
- `worktree`：每个 ticket 独立 branch/worktree，适用于多 session 并发
|
||
- `auto`：无其他活动 claim 时使用 in-place，否则使用 worktree
|
||
|
||
计划并发时，第一个 session 就必须指定 `worktree`。明确不并发时可使用
|
||
`in-place` 或 `auto`，不必创建 worktree。
|
||
|
||
in-place 模式要求 checkout 无非 `.scratch` 改动、HEAD 非 detached，且目标 branch
|
||
未被其他 worktree 占用。主循环不得自动 stash、reset、覆盖或丢弃改动。
|
||
|
||
`main_loop.py` 只支持 local Markdown tracker，并要求所有 sessions 共享同一文件系统、
|
||
control checkout 和 Git common directory。远程 tracker 可以由 Matt skills 单独使用，
|
||
但本主循环没有远程 tracker adapter，不能接入远程 claim/finish 状态。跨机器或独立
|
||
clone 的并发不受支持，不得把两份 `.scratch/` 当成同一队列。
|
||
|
||
## 主循环命令
|
||
|
||
### 入队和状态
|
||
|
||
```bash
|
||
python {{PLAYBOOK_SCRIPTS}}/main_loop.py enqueue \
|
||
--state-root .scratch --feature <feature-slug>
|
||
|
||
python {{PLAYBOOK_SCRIPTS}}/main_loop.py status \
|
||
--state-root .scratch
|
||
```
|
||
|
||
### 领取
|
||
|
||
`<owner>` 必须是当前 session 全局唯一且稳定的标识，例如
|
||
`<agent>-<UTC timestamp>-<random suffix>`。不得在并行 session 间复用 `codex`、`claude`
|
||
等通用名称；同一 owner 的重复 claim 只用于原 session 恢复自己的 ticket。
|
||
|
||
```bash
|
||
python {{PLAYBOOK_SCRIPTS}}/main_loop.py claim \
|
||
--state-root .scratch --repo-root . \
|
||
--owner "<owner>" --isolation in-place|worktree|auto
|
||
```
|
||
|
||
stdout 返回 `FEATURE`、`TICKET`、`CONTROL_ROOT`、绝对 `STATE_ROOT`、`WORKSPACE`、
|
||
`BRANCH`、`BASE` 和 `ISOLATION`：
|
||
|
||
- `CONTROL_ROOT` 是共享 Git control checkout
|
||
- `STATE_ROOT` 是唯一状态目录；它不必位于 `WORKSPACE` 内
|
||
- `WORKSPACE` 是当前 ticket 的代码工作区
|
||
|
||
领取成功后立即读取 `<STATE_ROOT>/<FEATURE>/spec.md` 和
|
||
`<STATE_ROOT>/<FEATURE>/issues/<TICKET>-*.md`；不得在 claim 前根据 frontier 猜测本 session
|
||
将领取哪个 ticket。后续 review 也必须使用这两个已领取上下文，而不是 worktree 内相对
|
||
`.scratch` 的偶然副本。
|
||
|
||
实现、提交和 review 必须在返回的 `WORKSPACE`/`BRANCH` 中完成。heartbeat、reclaim、
|
||
finish、status、block/release-feature 和 integrate 必须使用
|
||
`--state-root "<STATE_ROOT>"`，不得在 ticket worktree 中使用相对 `.scratch`。
|
||
|
||
同一 owner 重复 claim 恢复原 ticket。其他 owner 不得接管；失联时使用显式 reclaim。
|
||
|
||
### 心跳和接管
|
||
|
||
claim 的 stale 租约固定为 30 分钟，调用者不得缩短。claim 存续期间至少每 10 分钟发送一次
|
||
heartbeat，并在预计耗时较长的验证、构建或 review 前后各发送一次。无法继续维持 heartbeat
|
||
时，使用 `finish --result released|blocked` 明确交还或阻塞 ticket。
|
||
|
||
```bash
|
||
python {{PLAYBOOK_SCRIPTS}}/main_loop.py heartbeat \
|
||
--state-root "<STATE_ROOT>" \
|
||
--feature <feature> --ticket <NN> --owner "<owner>"
|
||
|
||
python {{PLAYBOOK_SCRIPTS}}/main_loop.py reclaim \
|
||
--state-root "<STATE_ROOT>" --repo-root "<CONTROL_ROOT>" \
|
||
--feature <feature> --ticket <NN> --owner "<new-owner>"
|
||
```
|
||
|
||
reclaim 只允许接管 stale claim，并保留原 branch、worktree 和未提交改动。
|
||
|
||
### Review 适配契约
|
||
|
||
调用 Matt `code-review` 时不得依赖其自动搜索或交互补问，必须显式提供：
|
||
|
||
- fixed point：ticket review 使用 claim 的 `BASE` 或重试返回的 `FEATURE_HEAD`；feature review
|
||
使用最新 `main` HEAD
|
||
- ticket review 的 Spec sources：逻辑路径 `.scratch/<feature>/spec.md` 与
|
||
`.scratch/<feature>/issues/<ticket>-*.md`，实际从绝对 `STATE_ROOT` 解析
|
||
- feature review 的 Spec sources：`.scratch/<feature>/spec.md` 和该 feature 的全部 ticket
|
||
acceptance criteria，实际从绝对 `STATE_ROOT` 解析
|
||
|
||
只有对应 axis 零个未解决的硬 finding 时才能记录 `pass`：
|
||
|
||
- `standards=pass`：没有未解决的仓库标准违规；baseline smell 属 judgement call，必须逐项记录
|
||
已修复或带理由接受，但不会仅因被提出就自动失败
|
||
- `spec=pass`：没有遗漏、部分实现、错误实现或未授权范围扩张
|
||
|
||
任一来源缺失、Spec axis 被跳过、review 尚在询问输入，或仍有未解决的硬 finding 时，
|
||
不得据此填写 `standards=pass` 或 `spec=pass`。修复会改变 `HEAD`，因此必须重新运行受影响
|
||
验证和完整双轴 review，不能沿用旧报告。
|
||
|
||
### Ticket 完成或状态转换
|
||
|
||
`resolved` 前必须先提交实现，再按 Review 适配契约对 `BASE...HEAD` 运行 Matt
|
||
`code-review` 的 Standards/Spec 双轴审查。
|
||
验证证据必须包含被验证 commit，review 证据必须包含被审查 commit 和固定 base；任意
|
||
非空文本或裸 `pass` 不能替代结构化证据。
|
||
|
||
```bash
|
||
python {{PLAYBOOK_SCRIPTS}}/main_loop.py finish \
|
||
--state-root "<STATE_ROOT>" --repo-root "<CONTROL_ROOT>" \
|
||
--feature <feature> --ticket <NN> --owner "<owner>" \
|
||
--result resolved \
|
||
--implementation-commit <HEAD> \
|
||
--feature-head <已验证feature HEAD> --review-base <同一feature HEAD> \
|
||
--verified "commit=<HEAD>; result=pass; <实际局部验证证据>" \
|
||
--reviewed "commit=<HEAD>; base=<review-base>; standards=pass; spec=pass"
|
||
```
|
||
|
||
首次 review base 是 claim 返回的 `BASE`。feature HEAD 已推进时返回
|
||
`RETRY: feature advanced` 和新的 `FEATURE_HEAD`；把该 `FEATURE_HEAD` 合入 ticket branch，
|
||
重新运行受影响验证，并以它作为新的 review base 重跑双轴 review。重试时
|
||
`--feature-head`、`--review-base` 和 review evidence 的 `base` 必须都使用该新值，验证与
|
||
review evidence 的 `commit` 必须等于新的 ticket `HEAD`。只有成功集成到 feature branch
|
||
后 ticket 才变为 `resolved`。
|
||
|
||
其他转换：
|
||
|
||
```bash
|
||
python {{PLAYBOOK_SCRIPTS}}/main_loop.py finish \
|
||
--state-root "<STATE_ROOT>" --repo-root "<CONTROL_ROOT>" \
|
||
--feature <feature> --ticket <NN> --owner "<owner>" \
|
||
--result blocked|skipped --reason "<明确原因>"
|
||
|
||
python {{PLAYBOOK_SCRIPTS}}/main_loop.py finish \
|
||
--state-root "<STATE_ROOT>" --repo-root "<CONTROL_ROOT>" \
|
||
--feature <feature> --ticket <NN> --owner "<owner>" \
|
||
--result released
|
||
```
|
||
|
||
release 返回 `ready-for-agent` 并保留 workspace；blocked ticket 可由原 owner release 后恢复。
|
||
|
||
### Feature 集成阻塞
|
||
|
||
ready-to-integrate feature 若因 main 同步冲突或人工决策暂时不能集成，必须显式记录；
|
||
这样主循环才会继续为后序 feature 分配开发工作：
|
||
|
||
```bash
|
||
python {{PLAYBOOK_SCRIPTS}}/main_loop.py block-feature \
|
||
--state-root "<STATE_ROOT>" --feature <feature> --reason "<明确原因>"
|
||
|
||
python {{PLAYBOOK_SCRIPTS}}/main_loop.py release-feature \
|
||
--state-root "<STATE_ROOT>" --feature <feature>
|
||
```
|
||
|
||
release 后该 feature 重新成为队首 `INTEGRATION_REQUIRED`。后序 feature 即使已开发完成，
|
||
仍不得越过它集成到 main。
|
||
|
||
### Feature 顺序集成
|
||
|
||
feature 必须吸收最新 `main`，完成 feature 验证、main 候选验证和最终双轴 review：
|
||
|
||
```bash
|
||
python {{PLAYBOOK_SCRIPTS}}/main_loop.py integrate \
|
||
--state-root "<STATE_ROOT>" --repo-root "<CONTROL_ROOT>" \
|
||
--feature <feature> --feature-head <已验证feature HEAD> \
|
||
--verified "commit=<feature HEAD>; result=pass; <feature级验证证据>" \
|
||
--main-verified "commit=<feature HEAD>; result=pass; <main候选验证证据>" \
|
||
--reviewed "commit=<feature HEAD>; base=<最新main HEAD>; standards=pass; spec=pass"
|
||
```
|
||
|
||
partial feature 还需 `--allow-partial`。返回 `RETRY: feature needs main sync` 时，
|
||
先在 feature integration workspace 合并最新 main；若发生冲突，先 `block-feature`，解决后
|
||
`release-feature`，重新验证和 review 后再调用。
|
||
|
||
## Git 与证据门禁
|
||
|
||
1. 每个 ticket 使用 `ticket/<feature>/<NN>-<slug>` branch
|
||
2. 每个 feature 使用 `feature/<feature>` branch
|
||
3. 按 TDD 完成一个可观察行为切片并运行局部验证
|
||
4. 提交全部实现，使 `HEAD` 成为可审查固定点
|
||
5. 首次以 claim 的 `BASE` 运行 `code-review`；同步推进后的 feature 时改用新的
|
||
`FEATURE_HEAD`
|
||
6. 修复 finding 后重新提交、验证和 review
|
||
7. `finish` 校验验证/review commit、review base 和 feature HEAD，再集成 ticket
|
||
8. `integrate` 把两级验证和最终 review 绑定到 feature HEAD，并把 review base 绑定到
|
||
最新 main HEAD
|
||
|
||
局部 ticket 验证、feature 验证和 main 候选验证是三个独立门禁，不能互相替代。
|
||
证据必须来自实际 fresh run；无法运行时不得伪造 `pass`。
|
||
|
||
## 辅助能力
|
||
|
||
以下能力在对应阶段内按需使用，不替代上面的入口路由和证据门禁：
|
||
|
||
| Skill | 触发条件 |
|
||
| ---------------- | ----------------------------------- |
|
||
| `codebase-recon` | 架构、跨模块、重构、迁移或风险不明 |
|
||
| `brooks-audit` | 架构边界和长期维护性审查 |
|
||
| `commit-message` | 需要检查 staged diff 或生成提交信息 |
|
||
|
||
## 需要确认的场景
|
||
|
||
设计阶段由 `grilling` 收敛所有决策。执行 ticket 时仅在以下情况暂停确认：
|
||
|
||
- ticket/spec 仍存在会改变实现的真实歧义
|
||
- 需要 spec 未授权的行为、兼容性或架构取舍
|
||
- 需要破坏性操作、覆盖他人改动或扩大任务范围
|
||
|
||
已明确预期行为的 bug 按 `diagnosing-bugs` 路由推进；符合既有模式的小改动、测试补齐和
|
||
已批准 ticket 范围内的实现不重复需求采访。
|
||
无交互模式下不得替用户作设计决策；将 ticket 标记 blocked 并记录原因。
|
||
|
||
## Session 收尾
|
||
|
||
- 运行与声明相匹配的 fresh verification
|
||
- ticket 执行必须通过 `finish` 写回；不得手工改状态
|
||
- 列出已完成、未完成、验证证据、风险和下一步
|
||
- 只提交当前 ticket/feature 相关改动，不混入其他 session 差异
|
||
- 工作未结束时在阶段边界按 Continue -> clear -> handoff -> subagent -> compact 的顺序选择
|
||
去向；不要仅因上下文过长就创建 handoff
|
||
|
||
---
|
||
|
||
**最后更新**：{{DATE}}
|