playbook/templates/AGENT_RULES.template.md

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 或设计变更使用以下顺序：

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-me 只用于无仓库的一次性讨论
• 进入 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
• 设计问题需要 runnable answer 时，从原设计会话 handoff 到独立目录运行 prototype，再 handoff 结论回原设计会话
• 已由 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/ 当成同一队列。

主循环命令

入队和状态

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。

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。

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 不能替代结构化证据。

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。

其他转换：

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 分配开发工作：

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：

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	架构边界和长期维护性审查
codebase-migrate	大规模迁移或宽重构
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}}