用途
Architecture-Design 是一个架构预检配套技能(companion gate),属于 souliane/teatree 仓库。它由实现类技能(t3:code、t3:ticket 用于新功能、t3:retro 当 retro 涉及技能时)通过 requires: [architecture-design] 声明传递加载,从而在编码开始之前自动加载。其目的是将“先设计,再编码”这一步骤编码为结构,而非依赖文字上的警觉。
该技能的范围限定于本仓库的约定——BLUEPRINT 对齐、FSM 阶段边界、扩展点契约、依赖方向。它回答的是“这个变更是否契合 teatree 的架构”,而不是“如何整体组织智能体工作”。
主要能力
该技能提供十项架构检查,当工作满足以下任一条件时触发:
- 触及 src/teatree/cli/、src/teatree/core/、src/teatree/loop/scanners/、src/teatree/agents/、OverlayBase、scanner 注册或任何 *Backend Protocol
- 跨越 FSM 阶段边界(引入或移动 Ticket.State 转换)
- 在 src/teatree/ 下引入新模块
- 更改 Protocol 表面或入口点契约
- 更改 BLUEPRINT.md 或任何 docs/blueprint/*.md 附录
战术性修复(拼写错误、窄字符串更改、单调用点 bug)跳过该门禁,实现者在 PR 正文中注明。
十项检查包括:
- BLUEPRINT § 对齐——引用工作触及的 BLUEPRINT 章节,若矛盾则在同一 PR 中更新 BLUEPRINT。
- FSM 阶段边界——列出跨越的阶段、转换方法和依赖的 FSM 条件。
- 扩展点契约——列出消费该契约的每个 overlay/scanner/hook。
- 组件边界——论证模块选择,若跨两类则拆分。
- 依赖方向——阅读自动生成的依赖图,添加导入后运行 uv run tach check 验证无反向边。
- 测试表面——为每个行为命名测试文件和断言。
- 韧性不变量(#1192)——对外部写入验证五项不变量:重读验证、回退传输、幂等性、心跳、子智能体返回契约。
- 身份与键规范化——完全限定形式为规范键,一个源真函数在每个边界向上规范化。
- 行为保留/能力删除——枚举旧代码处理的每个行为,标记保留或丢弃;隐私/泄漏/安全匹配器的收窄需用户明确签署。
- 可移除性/工具与数据——组件能否无级联删除;属于工具(代码/门禁/FSM)还是数据/配置。
此外,该技能还提供反模式目录(docs/generated/antipattern-catalog.md,源自 src/teatree/quality/antipatterns.yaml)作为机器检查的超集,以及架构预检模板。
使用方式
工作流程:
- 阅读 BLUEPRINT.md 及所触及章节的附录。
- 对提议的变更运行十项检查。
- 在工作树本地的 ARCHITECTURE.md(gitignored)中起草预检,然后在打开 PR 时将摘要带入 PR 正文的 ## Architecture pre-check 部分。
- 移交给实现技能(t3:code),它从这里以 TDD 接手。
预检模板包含十个部分,对应十项检查。实现者在改动 src/ 之前填写模板。面向审查者的交付物是 PR 正文中的 ## Architecture pre-check 部分,携带相同的十项检查摘要。PR 正文中缺失或空的预检部分视为审查缺口。
确定性验证器 teatree.quality.architecture_precheck 在 PR 创建时触发警告——core.gates.architecture_precheck_gate 在 PR 创建的两个关键点针对 PR 正文运行它——当正文携带的预检部分缺少某项检查或仅有占位符时。预检不完整直到它携带真实答案。
适用场景
适用于 souliane/teatree 仓库中涉及架构变更的实现工作,包括触及核心模块、跨越 FSM 阶段、引入新模块、更改 Protocol 表面或 BLUEPRINT 文档的变更。
限制
该技能范围限定于本仓库的约定,不涵盖提供者级别的智能体架构决策树(如单次调用 vs 工作流 vs 智能体、工具表面编排、智能体分层、韧性模式)。后者由 agent-platform 供应商的 claude-api 技能覆盖,该技能是 Anthropic 特定的,teatree 默认不安装,仅作为可选推荐(t3 doctor 检查在缺失时显示为 INFO),操作者可在 Claude 上使用 apm install anthropics/skills/skills/claude-api#<pin> 安装。
该配套技能不阻止实现技能加载——它与它们并行加载。纪律在于实现者先阅读它;PR 审查强制要求预检(PR 正文中的 ## Architecture pre-check 部分)已产出。若 PR 正文的预检部分缺少某项检查,审查者将其作为 PR 上的讨论线程提出——在缺口关闭前不合并。可移除性检查(#10)还有确定性后备:core.gates.architecture_precheck_gate 在 PR 创建时警告(仅警告,镜像开放问题门禁)。
通用规划方法论委托给 obra/superpowers/writing-plans。teatree 特定的增值是上述十项检查架构通过,以及实现者在触及 src/ 之前填写的模板。
关于收费、价格、平台等具体信息,资料中暂未提供。