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.
This commit is contained in:
@@ -0,0 +1,68 @@
|
||||
---
|
||||
name: subagent-driven-development
|
||||
description: "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. 自动质量门(每任务,机器判定)
|
||||
|
||||
```bash
|
||||
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`),纯机械改动跳过。
|
||||
@@ -0,0 +1,59 @@
|
||||
# Claude Subagent Implementer Prompt Template
|
||||
|
||||
派发实现 subagent(`Agent` 工具,`subagent_type=general-purpose`)时,以下面模板为 prompt 主体,填好方括号内容。新任务开新 subagent;同一任务的返修用 `SendMessage(to: agentId)`。
|
||||
|
||||
---
|
||||
|
||||
```
|
||||
You are implementing Task N: [task name] in the PolyGateway repository.
|
||||
|
||||
A controller spawned you, will read your output, verify your diff itself, and run an independent
|
||||
cross-model review before merge. Reviewers read actual code — optimize for being right, not for
|
||||
sounding right.
|
||||
|
||||
## Task Description
|
||||
|
||||
[任务全文,从 plan 逐字粘贴。不要给文件路径让 subagent 自己去找。]
|
||||
|
||||
## Context
|
||||
|
||||
[背景:该任务在整体设计中的位置、依赖、既有文件与约定。给足上下文,省一次 NEEDS_CONTEXT 往返。]
|
||||
|
||||
## Working Directory
|
||||
|
||||
[worktree 绝对路径]
|
||||
|
||||
## Project Conventions (non-negotiable, gates enforce these)
|
||||
|
||||
- 先读根目录 `CLAUDE.md`(库铁律、代码规范、目录规则)与 `research-wiki/ARCHITECTURE.md` 相关章节。
|
||||
- **目录**: 库代码只进 `src/polygateway/`(内核 ports/types/errors + middleware/transports/backends/telemetry/structured);测试进 `tests/{unit,integration,e2e}/`;`scripts/` 只放 `.sh`;根目录不得出现 `.py`;禁止 `helpers/ common/ shared/ misc/ lib/` 目录名。
|
||||
- **`reference/` 只读**,绝不修改(有 hook 硬拦截)。它是迁移蓝本:涉及迁移的任务必须逐段比对参考实现,不得简化核心逻辑。
|
||||
- **conda 环境**: 一切 Python 命令经 `conda run -n PolyGateway <cmd>`,不裸调 pytest/ruff。
|
||||
- **中文 Docstring**(模块/类/公共函数)、loguru 而非 print、公共函数完整类型注解、严禁裸 except 与 except Exception: pass、敏感信息只走 .env。
|
||||
- **测试证据**: 每个行为变更须有先失败后通过的测试证据(结果门);用真实样本或其二次构造。
|
||||
- 超过 30 秒的命令在 tmux 中运行(`tmux new-session -d -s sdd-taskN-<name> "<cmd>"`)。
|
||||
- 不做任务外的重构/抽象;文件长得不健康就在 NOTES 里标记,让控制器决定。
|
||||
|
||||
## Escalation
|
||||
|
||||
你无法与控制器交互式提问。真被卡住时不要猜:以 `STATUS: NEEDS_CONTEXT`(缺信息)或
|
||||
`STATUS: BLOCKED`(无法完成)结束,并具体说明卡点、已尝试什么、需要什么帮助。
|
||||
非阻塞的判断题(如 helper 放哪),选最站得住脚的做法实现,并在 NOTES 里写明供审查者挑战。
|
||||
|
||||
## Your Job
|
||||
|
||||
1. 精确实现任务所述——不多不少。
|
||||
2. 写测试并留下红→绿证据;跑 `conda run -n PolyGateway pytest` 与 ruff/radon,全绿。
|
||||
3. 按语义分段提交,常规提交信息格式(见 commit skill 规则,无 AI 签名)。
|
||||
4. 交付前自查:spec 每条都实现了吗?有没有 spec 外的东西?报告里的每句话对得上 diff 吗?
|
||||
|
||||
## Report Format (required — last thing in your output)
|
||||
|
||||
---
|
||||
STATUS: <DONE | DONE_WITH_CONCERNS | NEEDS_CONTEXT | BLOCKED>
|
||||
COMMIT_SHAS: <short SHAs, or "none">
|
||||
FILES_CHANGED: <paths, or "none">
|
||||
TESTS: <"all passing: X/Y" | "failing: <details>" | "not applicable">
|
||||
NOTES: <STATUS != DONE 时必填;顾虑、判断题、具体卡点写这里>
|
||||
---
|
||||
```
|
||||
@@ -0,0 +1,61 @@
|
||||
# Merge Reviewer Prompt Template(合并前一次性独立审查)
|
||||
|
||||
全部任务完成、自动质量门全绿后,用 `/codex:rescue --fresh --wait` 以本模板做**一次**只读审查,范围是整条分支。Codex 不可用时,同一模板派给全新上下文的 Claude verifier subagent(只读)。
|
||||
|
||||
---
|
||||
|
||||
```
|
||||
Codex review (read-only) — pass this as the /codex:rescue --fresh --wait prompt body:
|
||||
|
||||
description: "Pre-merge review for <branch>"
|
||||
prompt: |
|
||||
You are the independent pre-merge reviewer for work implemented by Claude subagents in the
|
||||
PolyGateway repository. You are read-only: read diffs and report, do not edit code.
|
||||
|
||||
## Plan / Requirements
|
||||
|
||||
[plan 全文或其需求部分,逐字粘贴]
|
||||
|
||||
## Scope
|
||||
|
||||
Working directory: [绝对路径]
|
||||
Commits to review: [分支上全部 SHA,或 base..head 区间]
|
||||
|
||||
## Do Not Trust Reports
|
||||
|
||||
实现方的自述可能不完整或过于乐观。一切以 `git show <sha>`、`git diff <base>..<head>` 与直接
|
||||
读文件为准,逐条独立核验。
|
||||
|
||||
## Review Dimensions (one pass, all of them)
|
||||
|
||||
1. **Spec 符合性**: plan 每条需求能否指到具体实现行?有无缺失、多余(未要求的功能/flag/依赖)、
|
||||
误解(接口/位置/签名与 plan 不符)?测试是在测 spec 要求的行为,还是在测"碰巧写出的代码"?
|
||||
有没有被删除或弱化的既有测试?
|
||||
2. **跨任务集成**: 任务间接口漂移、跨文件重复逻辑、早期任务留下的死代码、日志/配置/错误路径
|
||||
的跨任务一致性——这些是单任务审查抓不到的。
|
||||
3. **功能质量**: 职责划分、错误处理(吞异常/静默回退?)、并发与取消安全(CancelledError 穿透?)、
|
||||
降级方向是否符合 CLAUDE.md 库铁律、测试是否覆盖边界而非只有 happy path。
|
||||
4. **迁移保真**(若涉及 reference/ 蓝本迁移): 对照参考实现,核心逻辑(分支条件、Lua 语义、
|
||||
状态机、退避公式)是否被简化或改变语义而未在设计中声明。
|
||||
5. **明显过度设计**: 无人使用的参数/扩展点、可以是函数的类、不必要的间接层(YAGNI)。
|
||||
|
||||
## Calibration
|
||||
|
||||
只报会造成真实问题的项。措辞偏好与格式吹毛求疵不报(自动工具已管)。
|
||||
- Critical — 真实 bug、数据损坏、安全问题、破坏下游迁移承诺。必修。
|
||||
- Important — 维护痛点、脆弱代码、spec 缺口。应修。
|
||||
- Minor — 顺手可改,不阻塞。
|
||||
|
||||
## Report Format
|
||||
|
||||
Verdict: <APPROVED | CHANGES_REQUESTED>
|
||||
Spec gaps: <bullets 或 "none">
|
||||
Integration: <bullets 或 "none">
|
||||
Issues:
|
||||
Critical: <file:line + 问题,或 "none">
|
||||
Important: <file:line + 问题,或 "none">
|
||||
Minor: <file:line + 问题,或 "none">
|
||||
Assessment: <一段话:整体质量、能否合并、跨切面问题>
|
||||
|
||||
APPROVED = Critical 与 Important 均为 none。否则控制器将把发现发回修复并复审。
|
||||
```
|
||||
Reference in New Issue
Block a user