Files

T

iomgaa 3058f4c744 chore: bootstrap project scaffolding

Add architecture doc (research-wiki/ARCHITECTURE.md), CLAUDE.md with
tiered SOP for Fable 5, adapted .claude skills/hooks/settings, package
skeleton (src/polygateway), pyproject with import-linter contracts,
Makefile, .env.example and smoke test.

2026-07-20 00:49:10 -04:00

4.0 KiB

Raw Permalink Blame History

name, description

name	description
subagent-driven-development	Optional executor for large approved plans (many mostly-independent tasks): delegate each task to a fresh Claude subagent, run an automated quality gate per task, and one independent Codex review before merge. For small or tightly-coupled plans, implement directly instead.

Subagent-Driven Development

何时使用

适用: 已有批准的 plan、任务多(≥3)且大体相互独立、值得为每个任务开独立上下文。
不适用: 小计划、任务强耦合、探索性工作——直接实现更省更好。

结构:Claude 主会话做控制器;每个任务派一个全新 Claude subagent 实现;任务完成跑自动质量门;全部任务完成后、合并前做一次 Codex 独立审查(跨模型,消除自评盲区)。

流程

1. 读计划,建任务清单

读一遍 plan,把每个任务的全文与上下文提取出来,进 TodoWrite。之后不再让 subagent 去读 plan 文件——派发时把任务全文直接贴进 prompt。

若项目已建 graphify 知识图谱(graphify-out/ 存在),先 /graphify . --update 刷新;未建图则跳过,不阻断。

2. 派发实现 subagent(每任务一个,全新上下文)

用 Agent 工具(subagent_type=general-purpose),prompt 用 ./claude-implementer-prompt.md 模板填充(任务全文、上下文、绝对路径)。记下 agentId。

同一任务的返修一律 SendMessage(to: agentId) 发回原 subagent(保留其上下文);只有下一个任务才开新 subagent。
subagent 以结构化 STATUS 块收尾:DONE → 进质量门;NEEDS_CONTEXT → 补上下文继续;BLOCKED → 评估(补上下文/拆任务/计划有误则上报人类);缺失 STATUS 块按 BLOCKED 处理。

3. 自动质量门(每任务,机器判定)

conda run -n PolyGateway ruff format --check <changed_files>
conda run -n PolyGateway ruff check <changed_files>
conda run -n PolyGateway radon cc <changed_files> -n C -s   # C 级及以下复杂度即失败
conda run -n PolyGateway pytest tests/ -x -q
# 结构检查: 无裸 except / except Exception: pass;核心文件不超 200 行

失败 → 汇总工具输出,SendMessage 发回原 subagent 修,最多 2 轮,仍失败则上报人类。仅格式问题可由控制器直接 ruff format 修掉。测试超 30s 的在 tmux 里跑(tmux new-session -d -s sdd-task<N> "<cmd>"),便于人类 attach。

不信任 subagent 自述: 标记任务完成前,控制器亲自看 git diff 确认变更真实存在。

4. 合并前一次 Codex 独立审查(整分支)

全部任务完成、质量门全绿后,用 /codex:rescue --fresh --wait 按 ./merge-reviewer-prompt.md 做一次只读审查,范围是整条分支(所有 SHA + plan 全文),一次覆盖:spec 符合性(缺失/多余/误解)、跨任务集成问题、功能质量、明显的过度设计。

Critical/Important 问题 → 发回对应 subagent(或自己)修复,复审至清零。
前置:Codex 插件可用(/codex:setup 报 ready);审查模型用 .codex/config.toml 的默认强配置。Codex 不可用时,降级为派一个全新上下文的 Claude verifier subagent 按同一 prompt 审(见 verification-before-completion)。

5. 收尾

/graphify . --update(若在用),然后交给 finishing-a-development-branch。

纪律(约束点)

连续执行,任务间不停下来找人类确认;只有 BLOCKED 无解、真歧义、全部完成三种停法。
每任务提交留痕;严禁把多个任务squash成一坨再审。
审查不接受"差不多就行":Critical/Important 清零才合并。

Companion files

./claude-implementer-prompt.md — 实现 subagent 的 prompt 模板。
./merge-reviewer-prompt.md — 合并前一次性 Codex 审查的 prompt 模板。

Wiki 留痕(`research-wiki/` 存在时)

产生可复用实现知识或有价值审查意见的任务,记 plan/review 实体并连边(工具 .claude/tools/research_wiki.py,类型 implements/informs),纯机械改动跳过。

4.0 KiB Raw Permalink Blame History