| name | taiyi-architect |
| description | TaiyiForge 辅助 — 架构决策记录 ADR(长期影响决策的可追溯补充)。OpenCode / Claude / Codex / Cursor 通用。 |
taiyi-architect
目的
把长期难逆的技术决策从 DESIGN.md 抽成独立 ADR,供未来变更、onboarding 和 review 追溯——不替代 taiyi-design,而是补充「为什么当时这样选」。
何时使用
| 决策类型 | 示例 | 建议 |
|---|
| 数据与存储 | 新表、迁移策略、缓存层 | ADR |
| 安全与信任 | 鉴权模型、多租户隔离 | ADR |
| 集成边界 | 新微服务、第三方 SDK、事件总线 | ADR |
| 跨团队契约 | 公共 API、共享库破坏性变更 | ADR |
| 局部重构 | 重命名、抽函数 | 否,留在 DESIGN / TASK |
触发信号:
taiyi_assess 推荐 taiyi-architect
taiyi-design Options 里多个方案 Cost 差 ≥ 2x 或 运维负担显著不同
- dev 中发现原方案不可行,需正式废弃旧决策
输入
CHANGE.md、REQUIREMENT.md、DESIGN.md
- (可选)
CONTEXT.md、taiyi-intel-scan 风险区
- 工程评审结论(如 gstack
plan-eng-review 摘要)
输出
- 路径:
.taiyi/changes/<slug>/adr/NNNN-<short-title>.md
- 编号:
0001 起递增,全仓库统一或每 slug 独立二选一(在首个 ADR 文首声明规则)
DESIGN.md 的 Decision 节须回链:ADR-0003 + 一句话摘要
ADR 结构(必填)
# ADR-NNNN: <标题>
## Status
proposed | accepted | deprecated | superseded by ADR-XXXX
## Context
<!-- 压力、约束、相关 AC / 风险 -->
## Decision
<!-- 我们决定 … -->
## Consequences
### Positive
- …
### Negative
- …
## Alternatives considered
| 方案 | 优点 | 缺点 | 为何未选 |
|------|------|------|----------|
| A | | | |
| B | | | |
## Links
- DESIGN.md §…
- REQUIREMENT.md AC-…
执行步骤
- 确认决策边界:一句话写清「本 ADR 解决什么 / 不解决什么」
- 收集约束:性能、合规、团队技能、上线窗口——来自 REQUIREMENT / CHANGE
- 列 ≥2 个真备选:含「维持现状」若合理;禁止 strawman
- 写 Decision:可执行、可验证(例如「用 PostgreSQL JSONB 存元数据,不用 Mongo」)
- 写 Consequences:诚实写负向(运维、迁移、锁定)
- 定 Status:设计阶段多为
proposed;人工确认后改 accepted
- 回写 DESIGN.md:Decision 表增加 ADR 链接;Open Questions 关闭对应项
- 若 supersede 旧 ADR:旧文 Status →
superseded,新 ADR 的 Links 互指
与主流程关系
taiyi-change → taiyi-requirement → taiyi-design
↓ ↓
taiyi-intel-scan taiyi-architect (按需)
↓ ↓
DESIGN.md + adr/
- ui-design / task / dev 不得违背
accepted ADR;若必须违背,先新 ADR 或走变更提案
- 集成阶段
CHANGELOG.md 可引用 ADR 编号说明破坏性变更
质量自检
与铁三角
- gstack
plan-eng-review:评审结论中「必须记录」项 → 升格为 ADR
- OpenSpec:若已
sync-openspec,ADR 摘要可同步到 design.md 脚注(非自动,人工摘一句)
禁止
- 用 ADR 堆细节实现(属 TASK / 代码注释)
- Status
accepted 但未回写 DESIGN
- 一 ADR 多决策(拆成多个编号)
- 在 dev 静默改架构不留 ADR(改走
taiyi-evolve + 新 ADR)