mcpField
A
architect

architect

github.com/thebeardedbearsas开发107202 次安装2 天前更新
代码仓库

关于 architect

面向采用 TDD 的开发者，在编写测试或代码前先产出架构规格。流程涵盖边界、契约、依赖、权衡和架构测试，并给出任务拆分等交付物。

主要功能

  1. 01识别功能涉及的架构边界
  2. 02定义边界输入、输出与副作用
  3. 03绘制依赖关系并检查依赖方向
  4. 04记录设计权衡与 ADR
  5. 05预先规划架构测试

适用场景

  1. 01为跨多个文件的新功能制定设计
  2. 02规划新模块或有界上下文
  3. 03设计技术迁移或外部集成
  4. 04在 TDD 前拆分架构与开发任务

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/thebeardedbearsas/claude-craft --skill architect

安装后在 Claude Code 中输入/architect确认已加载。

详细介绍

架构设计 — TDD 前的架构阶段

灵感来自 obra/superpowers。目标： 在编写任何测试或代码之前，产出一份架构规范。

黄金法则： 如果你无法画出图，就无法编写该功能的代码。

何时使用

情况是否需要架构阶段？
单文件 Bug❌ 否（直接进行 TDD）
新功能 < 3 个文件⚠️ 简短进行（10 分钟）
新功能 > 3 个文件✅ 必须
新模块/限界上下文✅ 必须
技术迁移✅ 必须
外部集成（API、MQ、DB）✅ 必须

5 个步骤

1. 确定边界

该功能会触及哪些边界？

  • 领域边界 — 涉及哪些限界上下文？
  • 层级边界 — Presentation / Application / Domain / Infrastructure？
  • 进程边界 — 同步 HTTP / 异步队列 / 事件驱动？
  • 数据边界 — 涉及哪些数据库、哪些表？
  • 所有权边界 — 哪个团队负责哪一部分？

产出： 列出跨越的边界。

2. 定义契约

为每个跨越的边界定义契约：

  • 输入：格式、类型、不变量、是否可空
  • 输出：格式、错误代码、目标延迟
  • 副作用：数据库写入、发出的事件、外部调用
  • 幂等性：契约是否具备幂等性？
  • 事务：是否原子化？是否最终一致？

产出： 函数/端点签名 + DTO。

3. 绘制依赖关系

谁依赖什么？依赖方向是什么？

[HTTP Controller] ──▶ [Use Case] ──▶ [Domain Service]
                                          │
                                          ▼
                                     [Repository] (interface)
                                          │
                                          ▼
                        [Postgres Adapter] ─implements─▶

检查：

  • 没有循环依赖（A → B → A）
  • 遵循 DIP（领域层不依赖基础设施层）
  • 从入口到业务层之间的调用层级不超过 3 层

产出： 图表（Mermaid、ASCII 或结构化文本）。

4. 列出权衡

对于每个不明显的决策，记录选择该方案的原因：

决策考虑过的替代方案选择该方案的原因
通过队列异步处理同步 HTTP延迟 >500ms，非即时关键操作
CQRS简单 CRUD读写比例为 20:1
事件溯源存储状态有法律审计需求

产出： 简短的 ADR（3-5 个要点）——如果是重大决策，请参阅 .claude/rules/10-documentation.md 了解正式 ADR。

5. 定义架构测试

在针对行为进行 TDD 之前，先定义架构测试：

  • 依赖关系测试（ArchUnit、Dephpend、deptrac）
  • 契约测试（OpenAPI 验证、契约测试）
  • 目标性能测试（p99 延迟、吞吐量）
  • 适用时进行多租户隔离测试

产出： Phase TDD 中要编写的架构测试列表。

交付物

架构阶段结束时，产出：

  1. 依赖关系图（最多 1 页）
  2. 边界契约（签名 + DTO）
  3. 主要权衡的简短 ADR
  4. 架构测试列表
  5. 拆分为原子任务（参阅 atomic-tasks 技能）

完成这些之后，才进入 TDD（Red/Green/Refactor）。

反模式

反模式解决方案
不画图就直接编码先画图，即使只花 5 分钟也足够
简单功能的架构阶段超过 2 小时YAGNI — 及时收尾
契约含糊不清（“User 对象”）使用严格类型，列出所有字段
忽略权衡必须编写简短 ADR
闭门造车式架构设计由同伴或子 Agent @tech-lead 审查

Claude Craft 集成

  • /workflow:design — 默认使用此技能
  • Agent @tech-lead — 可以产出架构阶段的交付物
  • 正式 ADR：参阅 /common:architecture-decision
  • Rule 04 SOLID + Rule 17 CQRS + Rule 14 Multitenant — 根据上下文查阅

Ressources

  • obra/superpowers
  • Rule .claude/rules/04-solid-principles.md
  • Rule .claude/rules/10-documentation.md (ADR)
  • Skill atomic-tasks

Date de dernière mise à jour : 2026-04-15 Version : 1.0.0

评论

支持 Markdown