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

3.4 KiB

Raw Blame History

name, description

name	description
brainstorming	Use before design-level creative work. MANDATORY when the change touches public API, port (Protocol) signatures, or architecture boundaries — these require an approved design and a human gate. For smaller changes (internal implementation, test fixes, tasks inside an approved plan), use your judgment: skip if requirements are already unambiguous.

Brainstorming Ideas Into Designs

把想法变成经过对比与确认的设计。产出是一份设计文档,不是代码。

触发边界(何时必须用)

情形	是否强制
变更公共 API、端口(Protocol)签名、架构边界(`ports.py`/`types.py`/`errors.py`、middleware 洋葱层次、依赖铁律)	强制,且设计必须经人类确认后才能实施
新增子系统/新组件、里程碑级功能	强制
内部实现、测试修复、已批准 plan 内的任务、文档修订	自判;需求无歧义即可直接做

不确定属于哪一类时,按"是否会改变库对下游三个项目的承诺"判断:会,就走设计。

核心要求(设计的验收标准)

一份合格的设计必须包含,缺一即不完整:

备选方案对比:至少 2-3 个可行方案、各自权衡、你的推荐及理由。只有一个方案 = 没有做设计。
旧版行为审计(仅重写/迁移类任务):本库大量工作是从 reference/ 三项目迁移治理代码。凡替换/重写既有模块,必须列出旧版全部行为(含持久化、崩溃恢复、幂等、断点续跑),逐条标注"保留 / 替换 / 有意放弃"。未声明的隐式丢弃 = bug。
非功能维度(逐条回答,允许"不适用"但必须写明):
- 并发与取消:并发调用下的行为?CancelledError 穿透路径?
- 降级方向:依赖的后端不可用时,静默降级还是报错?(对照 CLAUDE.md 库铁律)
- 幂等与重复:同一操作重复执行是否安全?
- 持久化与原子性:什么时候落盘?部分写入会不会损坏数据?
错误处理与测试策略:失败落入哪个错误分类?怎么测?

过程建议(非脚本)

先查 research-wiki/ARCHITECTURE.md 与相关 reference/ 代码,再提问;问题一次一个、能选择题就选择题;范围过大(多个独立子系统)先拆分再逐个设计。不做任务外的重构与抽象——设计只服务当前目标。

如需向人类展示视觉对比(布局/图示),可参考 visual-companion.md(可选工具,非流程)。

留痕与审批门(不可省略)

写设计文档: research-wiki/designs/YYYY-MM-DD-<topic>-design.md(≤400 行),并提交 git。
自审后送 Codex 独立审: 用 /codex:rescue --fresh --wait 只读审查(需求覆盖、内部一致性、与 ARCHITECTURE.md/CLAUDE.md 的冲突)。逐条核验其意见后就地修订——不盲从。模板见 spec-document-reviewer-prompt.md。
人类审批门: 凡触发"强制"档的设计,必须请人类审阅设计文档并明确同意后才进入 writing-plans。这是硬门,不因任何理由跳过。

Wiki 注册(research-wiki/ 存在时):

.claude/tools/research_wiki.py add_entity research-wiki/ --type design --id <slug> --title "<title>"
.claude/tools/research_wiki.py rebuild_index research-wiki/

在生成页中记录:选定方案、关键理由、被否决的备选及否决原因。

设计获批后的下一步是 writing-plans(若达到其触发规模),不要跳到实现类 skill。

3.4 KiB Raw Blame History