design-code-architecture

设计代码架构

为新应用设计架构：谨慎做好少数难以逆转且代价高昂的决策，其他方面则尽可能保持简单。这是一段包含八个阶段、可交互且可中途暂停后续接的旅程——每次决策前，Agent 都会先征求你的意见，并将结果记录在项目的 docs/ 文件夹中，因此你可以在任何阶段结束后暂停，稍后再继续。旅程从最基础、最难逆转的部分（边界、领域）开始，经过可调整的部分（数据、弹性），再到贯穿始终的跨领域实践（复杂性、可逆性、范围）。周末项目可以轻量地采用其中三个阶段；有资金支持、目标是发布产品的团队则可以采用整套方法。

核心原则

架构就是那些逆转代价高昂的决策：只审慎做出这些决策，其余所有代价低的决策都延后。 这项技能会安排各个阶段、提出决策问题，并将每项选择记录在 docs/ 中。各个组成技能负责提供方法——调用它们，而不是临时拼凑框架。整体策略是在昂贵决策前设置边界，将它们转化为廉价决策，从而让那些无法避免的高成本决策少到足以仔细做好。

旅程图

阶段	技能	回答的问题	产物
1	clean-architecture	源代码依赖是否指向内层——核心是否无需数据库、Web 或框架即可测试？	创建 docs/ARCHITECTURE.md
2	domain-driven-design	业务实际上如何划分？每个术语的含义是什么？	扩展 docs/ARCHITECTURE.md
3	system-design	实际负载真正需要的最简系统是什么？	扩展 docs/ARCHITECTURE.md
4	ddia-systems	每种工作负载需要哪种数据模型、存储引擎和一致性？	扩展 docs/ARCHITECTURE.md
5	software-design-philosophy	复杂性是隐藏在深层模块后，还是陷入了类膨胀？	扩展 docs/TECH-DEBT.md
6	release-it	依赖项变慢或宕机时，系统能否优雅降级？	创建 docs/RELIABILITY.md
7	pragmatic-programmer	哪个精简切片可以验证边界？哪些习惯能让边界保持可逆？	扩展 docs/TESTING.md + docs/TECH-DEBT.md
8	37signals-way	v1 必不可少的内容是什么？哪些推测性的抽象应该删掉？	扩展 docs/ARCHITECTURE.md + docs/TECH-DEBT.md

Operating Rules

1. 先恢复进度。 在做任何其他事情之前，先阅读 docs/DESIGN-CODE-ARCHITECTURE-PLAN.md 和 Journey Map 中的每一项产物。如果跟踪文件存在，用 3-5 行总结旅程状态，并询问要进入哪个阶段。完成条件：用户已确认入口点。有跟踪文件的旅程应恢复，而不是重新开始。
2. 仅在首次运行时进行 Intake。 如果没有跟踪文件：运行下方的 Intake，然后创建 docs/DESIGN-CODE-ARCHITECTURE-PLAN.md，并将每个阶段的状态设为 pending | in-progress | awaiting-evidence | done | deferred: reason | skipped: reason。完成条件：跟踪文件已创建，且用户已确认阶段计划。
3. 进入阶段。 说明该阶段的作用、需要做出的决定、产出的文档以及大致投入。提供继续 / 跳过 / 延后选项——标记为 GATE 的阶段可以延后，但不能跳过。用户选择继续后，将阶段标记为 in-progress。完成条件：用户已作出选择。
4. 调用技能及回退方案。 加载并使用该阶段的技能：每个阶段的 Invoke 行会通过 slug 指定技能——使用该技能执行阶段。如果该技能不可用，则提供：npx skills add wondelai/skills/<slug> --global。如果用户拒绝，则根据 Brief 执行阶段——采用最低可行方法。说明当前采用的模式。
5. 阶段内决策。 询问“与用户共同决定”下的每个问题，并提供具体选项和推荐方案。将选择记录在跟踪文件的 Key Decisions 中。默默作出的决定属于缺陷。
6. 阶段退出。 写入前，先展示文档草稿供用户确认。获批后：写入或扩展 docs/ 文件，更新跟踪文件（状态、Key Decisions、Next Actions）。完成条件：文件已写入，且阶段行显示 done。
7. 文档规范。 写入前先阅读；只有文件不存在时才新建，否则应在保留其他人内容的基础上扩展——添加或更新相应章节。docs/ 中的文件名必须使用大写。首次创建 docs/ 文件时，请参阅 references/artifact-templates.md；使用完整骨架创建文件（包含所有章节标题），然后填写阶段要求的章节。每条建议都必须写成复选框或表格行，并注明负责人和优先级。
8. 每个难以撤销的决策都必须先在 Decision Log 中记录一行（决策、原因、拒绝的备选方案），然后代码才能以此为前提。默认采用模块化单体：只有在有证据证明存在有界上下文时才拆分服务。

信息收集

创建跟踪文档前，请先询问以下问题：

1. 应用会做什么？真正构成竞争优势的功能是什么？（在阶段 2 中界定核心子域——决定哪些部分需要深入建模，哪些可以购买现成方案）
2. 你倾向于使用什么技术栈——语言、Web 框架、ORM、数据库？（决定阶段 1 的边界和阶段 4 的数据决策；这些只是细节，绝不是骨架）
3. 第一年实际会有多大负载——大致的日活用户数，以及每位用户主要会执行哪些操作？（决定阶段 3 的容量规划：先明确需求，再考虑解决方案）
4. 应用会调用哪些外部依赖——支付、电子邮件、大模型 API、物流、队列？（决定阶段 6 的集成点审查）
5. 哪些数据属于权威数据源？是否还有其他读取模式，例如搜索、分析或信息流？（决定阶段 4 的一致性和派生数据决策）
6. 是否有人验证过用户确实需要这个应用？（如果没有，先转到 create-business / create-app——不要为未经验证的想法做架构设计）
7. 有多少个团队会负责这个系统？你希望现在覆盖整个流程的多少部分？（决定是否进行可选的团队拓扑阶段，以及阶段 8 的投入程度）

阶段跳过启发式规则：如果第一年的负载远低于任何阈值，跳过阶段 3 的扩展机制，以及阶段 4 中大部分复制内容（单个带索引的数据库就是答案——记录下来并继续）；单团队应用可跳过可选的团队拓扑阶段。绝不要跳过阶段 1 或阶段 2——边界和领域模型是增量式工作，能让之后的每个决策都变得廉价；一旦有真实用户和外部调用，阶段 6 的弹性设计就不是可选项。然后根据模板创建跟踪文档，并确认计划。

完成条件：docs/DESIGN-CODE-ARCHITECTURE-PLAN.md 已存在，且每个阶段都已标明状态，用户也已确认计划。

阶段

阶段按所列顺序执行，从最难逆转的决策，到可调整的决策，再到横切关注点——每个阶段都假设前一阶段的产物已存在。根据运行规则，可以进入、跳过或推迟任何阶段；阶段 1–2 是增量式工作，能让之后的一切都更容易调整。

这些阶段构成一条与系统相对应的依赖链：领域驱动设计说明边界应该设在哪里（上下文和聚合边界）；整洁架构说明依赖应以什么方向跨越这些边界；数据密集型应用决定持久化层中各边界内部存放什么；系统设计说明实际需要多少基础设施——通常远少于预期。软件设计让模块保持深度，而不是不断增加浅层形式主义；《Release It!》强化集成点；《程序员修炼之道》提供能长期维持结构的横切习惯；《37signals Way》则通过限定时间并缩小范围来统筹全局。

阶段 1 — 划定边界（clean-architecture）

目的： 让业务规则独立于框架、数据库和供应商，使之后的每项决策都可替换——这一步能让其他所有决策都更灵活。

简述（备用）： 依赖规则——源代码依赖指向内层：框架 → 接口适配器 → 用例 → 实体；内层不能命名任何外层内容。数据库、Web 和供应商都是细节，是规则的插件。通过依赖倒置来强制执行：用例拥有一个仓库接口；Postgres/Stripe 的实现位于外层适配器中。只在真正易变的地方（数据库、外部服务、交付方式）划定完整边界；其他地方则合并层——重要的是依赖方向，而不是文件夹数量。

调用： 使用 clean-architecture 技能，结合一个具体的首个功能和初始收集的信息中确定的技术栈。让它为该功能分层（实体、带请求/响应模型的用例、仓库 + 网关接口、外层的 HTTP 控制器和数据库适配器），并指出哪些边界只是形式主义，哪些边界能在真正易变的地方发挥价值。

与用户共同决策：（1）模块化单体还是服务——默认选择具有清晰内部边界的模块化单体；共享数据模型的微服务是分布式单体，严格来说更糟。（2）哪些易变点现在要通过接口设立完整边界，哪些地方要合并层。

产出： 创建 docs/ARCHITECTURE.md，包含 ## System Context（功能说明、集成）、## Layer Map & Dependency Rule（各层、依赖关系；违规 | 位置 | 修复方案 | 状态），并在 ## Decision Log 中记录单体与服务之间的选择（日期 | 决策 | 原因 | 被否决的替代方案）。更新跟踪表。

完成条件： 已绘制层级图；首个功能已完成分层，框架/ORM 类型仅限于外层；核心部分的设计可在没有数据库/Web/框架的情况下测试；单体与服务之间的选择已记录为一条决策日志；阶段 1 显示为 done。

阶段 2 — 建模领域（domain-driven-design）

目的： 在业务实际分化的地方划定边界，让代码使用领域语言——现在这样做成本最低，也能从一张白纸开始建立词汇体系。

简述（备用）： 模型就是代码——构建通用语言，让团队用语成为代码用语。根据领域概念命名（Order.place()，而不是 OrderManager.process()）；如果某个名称不易确定，这是设计信号，而非麻烦。有界上下文：一个词在其中只有一种确切含义的区域（“Customer”在计费和支持场景中含义不同）——这就是未来服务的边界。聚合：负责维护不变量的小型根集群；内部保持即时一致，外部最终一致；通过 ID 引用其他聚合。将行为放入实体——不要创建贫血的数据包。

调用： 使用 domain-driven-design 技能，结合领域词汇和阶段 1 的层级图。要求它根据团队实际使用的词汇绘制有界上下文图，列出核心聚合及其不变量，并对细分领域进行分类（核心 / 支撑 / 通用）。

与用户共同决策：（1）同一个词在不同上下文中确实具有不同含义的地方——不要统一成一个全知模型。（2）哪些细分领域属于核心（深入建模），哪些属于通用（购买或使用开源软件——身份验证、电子邮件、支付）。

产出： 扩展 docs/ARCHITECTURE.md：添加 ## Bounded Contexts & Context Map（上下文、关系、防腐层）和 ## Domain Glossary (Ubiquitous Language)（术语 | 含义 | 代码名称）；在 ## Decision Log 中记录聚合和核心领域的选择。更新跟踪表。

完成条件： 已绘制上下文及其关系；词汇表列出了核心术语；每个聚合都说明了其不变量和按 ID 引用的对象；已选定核心细分领域；上下文边界与阶段 1 的层级图一致。

阶段 3 — 如实估算系统规模（system-design）

目的： 用数字证明系统可以有多小，从而跳过那些无法证明合理性的复杂机制。

简述（备用方案）： 从需求出发，而不是从解决方案出发。粗略估算：QPS = 日活用户数 × 每日操作数 ÷ 86,400，峰值为平均值的 2-5 倍；存储量 = 每日记录数 × 单条大小 × 保留期限。对于数百到数千名用户，单个带索引的数据库加上读路径缓存，可以支撑很长时间。按顺序扩展：先纵向扩展，然后采用 cache-aside（TTL + 显式失效），接着添加只读副本，最后才分片，而且只有在有证据时才分片。使用消息队列来解耦缓慢或突发的工作负载，使用 CDN 分发全球静态资源。过早分片和过早拆分服务都是明确列出的错误。

调用： 使用 system-design 技能，并结合需求收集阶段掌握的负载情况。询问平均和峰值 QPS、年度存储量、哪个组件最先成为瓶颈，以及一份明确列出当前不需要的技术（分片、副本、CDN、队列、多区域）的清单。

与用户共同决定： 根据数字决定哪些扩展措施现在实施，哪些暂缓（用户只有 50 名时，不要按 50k 名用户的规模来构建），以及是否有第一个需要移入消息队列的慢速工作负载。

产出： 在 docs/ARCHITECTURE.md 的 ## System Context 中补充实际负载情况和粗略估算数据；在 ## Decision Log 中记录每项扩展措施（现在采用／暂缓并注明触发条件）。更新跟踪表。

完成标准： 已记录平均／峰值 QPS 和年度存储量，已指出第一个瓶颈，并且每项扩展技术要么说明理由后采用，要么注明触发条件对应的数字后暂缓。

阶段 4 — 审慎做出数据决策（ddia-systems）

目的： 正确选择比代码更长久的部分——根据访问模式而非习惯来选择数据模型、存储引擎和一致性。

简述（备用方案）： 数据比代码更长久。根据访问模式选择模型——关系型适用于多对多关系和临时查询，文档型适用于具有局部性的自包含聚合，图适用于递归遍历；存储引擎则需要在读写之间权衡（LSM 的写入吞吐量与 B-tree 的读取延迟）。大多数数据库默认采用读已提交或快照隔离，而不是可串行化隔离——天真的先读后写会引发写偏斜（两位买家同时购买最后一件商品）。如果不变量要求如此，就显式加锁（SELECT ... FOR UPDATE）或使用可串行化事务。单主节点 + 只读副本是读密集型场景的默认方案；复制延迟意味着必须有意识地处理读己之写。将系统记录源与可重建的派生数据分开。

调用： 使用 ddia-systems 技能，并结合阶段 2 聚合数据所体现的工作负载以及阶段 3 的副本方案。按工作负载询问适用的数据模型和存储引擎、实际的默认隔离级别及其异常，以及哪些先读后写路径需要加锁。

与用户共同决定： (1) 根据各工作负载的适用性，选择单一数据存储还是多模型持久化。(2) 确定哪些路径需要加锁或使用可串行化事务，哪些路径可以容忍最终一致性；以及第二种读取模式（搜索、分析）是否值得通过 CDC 同步维护派生数据。

产出： 在 docs/ARCHITECTURE.md 的 ## Data & Storage Decisions 中补充数据模型、存储引擎、隔离级别、加锁路径、系统记录源与派生数据；并在 ## Decision Log 中记录决策理由。更新跟踪表。

完成标准： 已根据适用性为每种工作负载选定数据模型和存储引擎，已记录默认隔离级别，每条容易发生写偏斜的路径都已加锁或采用可串行化隔离，并且所有派生数据都定义了同步机制。

第 5 阶段 — 保持模块深邃（software-design-philosophy）

目的： 防止结构本身成为问题——用简单的接口隐藏内部机制，而不是把系统拆成浅层类。

简述（备用）： 复杂性是敌人；衡量每项决策的标准，是它能否让整个系统更简单。模块深度 = 功能 ÷ 接口复杂度——深层模块用小型接口隐藏强大功能；浅层模块（类膨胀）增加接口成本，却没有隐藏复杂性。清晰分层与深层模块相辅相成；清晰分层与类膨胀则不然。信息泄漏——一个设计决策反映在多个模块中——是最重要的危险信号之一；每条知识都应封装一次。战略优先于战术：投入 10-20% 的精力保持设计整洁；随着团队壮大，启动阶段走捷径会逐渐累积成债务。

调用： 使用 software-design-philosophy 技能，并采用第 1-2 阶段提出的模块集合。询问哪些浅层透传模块可以合并、哪些知识会跨边界泄漏，以及任何计划中的边界是否只是形式上的安排而非真正的深度。

与用户共同决定： 现在要将哪些浅层模块合并为更深的模块，同时避免过度合并真正不相关的事项；团队采用哪些设计约定（命名、行为放在哪里、每条知识对应一个文件）。

产出： 扩展 docs/TECH-DEBT.md 中的 ## Smell Inventory（添加浅层模块／信息泄漏条目，并记录已实施的合并），并在 ## Adopted Conventions 下记录达成一致的规则。更新跟踪器。

完成标准： 每个浅层模块群组都已合并或记录了修复方案；没有任何单一设计决策在多个模块中重复；设计约定已记录。

第 6 阶段 — 为故障而设计（release-it）

目的： 让系统在依赖变慢或宕机时能够优雅降级，而不是崩溃——现在设计好成本最低，不必等到凌晨 2 点再处理。

简述（备用）： 通过 QA 的软件不一定能在生产环境中存活。集成点是头号杀手；响应缓慢比没有响应更糟——挂起的依赖会耗尽线程和连接池，日志中却没有任何记录。不可妥协的要求：每个出站调用都必须设置连接超时和读取超时；关键调用必须使用熔断器（跳闸后断开，快速失败，并可半开恢复）；使用舱壁按依赖隔离连接池；重试必须采用退避策略并加入抖动。所有列表端点都必须分页（无界结果集会在真实数据下导致崩溃）；安排稳定运行状态下的清理工作。通过功能标志和向后兼容的扩展-收缩迁移，将部署与发布解耦。

调用： 使用 release-it 技能，并采用接入阶段列出的出站依赖。针对每个依赖询问超时值和熔断阈值、舱壁的设置位置、每项集成的优雅降级路径，以及深度健康检查 + RED 指标 + 扩展-收缩迁移的必要内容。

与用户共同决定： 熔断阈值、哪些依赖需要专用连接池、非关键依赖宕机时核心流程如何降级，以及值得信赖的回滚路径。前一千名用户阶段，应避免实施混沌工程／多区域故障转移。

产出： 创建 docs/RELIABILITY.md，包含 ## Integration-Point Audit（dependency | timeout | circuit breaker | bulkhead | retry policy | status）、## Query & Resource Findings、## Health Checks & Metrics 和 ## Deploy vs Release。更新跟踪器。

完成标准： 每个计划中的出站调用都设置了超时；关键依赖都配置了熔断器和舱壁；每个列表端点都已分页；已明确规定深度健康检查 + RED 指标 + 扩展-收缩迁移 + 可信赖的回滚；关键路径的审计条目均无待解决项。

阶段 7 — 验证各层连通并养成习惯（pragmatic-programmer）

目的： 通过构建一个贯穿所有层的精简真实切片，验证各层边界能够衔接，并确立让架构保持可逆的习惯。

简介（备用方案）： 示踪弹——构建一个精简但完全真实的纵向切片（HTTP → 用例 → 仓库 → 数据库 → 返回），并将其保留为生产代码，以便第二天获得端到端反馈，并在扩展各层之前证明边界能够衔接。可逆性：将每个供应商封装在自己的接口后面（分叉路口测试——你能在一周内更换数据库或 LLM 提供商吗？）。正交性：对某项需求进行重大更改时，只应涉及一个模块。DRY 针对的是知识，而不是巧合——合并重复的规则，保留仅仅相似的内容。破窗效应：发现第一个临时方案时就修好，或登记跟踪工单并暂时封存。

调用： 使用 pragmatic-programmer 技能和阶段 1 的边界。请它设计一个尽可能精简、能端到端贯穿每一层的示踪弹，为每个供应商设计一个适配器接口，并审查哪些更改会触及多个模块，或哪些供应商 API 会泄漏到业务逻辑中。

与用户共同决定： 哪个切片作为示踪弹（一个经过身份验证的核心操作，功能最少化）；破窗策略和每轮迭代的技术债预算；哪些供应商应优先拥有专属接口。

产物： 扩展 docs/TESTING.md 中的 ## Test Strategy、## Safety Net Map（将示踪弹路径作为第一个端到端测试）和 ## CI Gates；扩展 docs/TECH-DEBT.md 中的 ## Debt Budget & Broken-Windows Policy 和 ## Adopted Conventions（可逆性、正交性）。更新跟踪表。

完成标准： 示踪弹切片能够贯穿每一层端到端运行，并被设为第一个 CI 门禁；每个供应商都通过专属接口接入；破窗策略和技术债预算均已记录。

阶段 8 — 缩减范围，聚焦核心（37signals-way）

目的： 决定是否发布这些内容——锁定时间、灵活调整范围，并在推测性抽象变成需要承担的复杂性之前将其删除。

简介（备用方案）： 少做一些——最好的产品能把更少的事情做好；半成品胜过粗制滥造的全套产品。设定投入意愿（这项工作真正值得投入的时间），并缩减范围以适应投入，而不是估算一个范围不断膨胀的开放式架构。YAGNI：每一种推测性抽象（通用插件系统、事件溯源、面向零用户的可配置多租户）都是把决定推迟到想象中的未来，却要付出当前复杂性的代价。做出细小且可逆的决策；默认拒绝，让真正重要的决策有空间落实。绝不要为了节省时间而砍掉少数难以撤销的决策。

调用： 使用 37signals-way 技能，并提供阶段 1 至 7 的完整架构计划。请它按照固定投入意愿规划工作，区分发布必需项与过度设计，指出可能陷入的无底洞，并列出应删除或用最简单可行方案替代的推测性抽象。

与用户共同决定： v1 架构工作的投入意愿；哪些抽象现在就删除、通过重新审视触发条件暂缓，或用最简单的方案替代；确认没有仅仅为了节省时间而砍掉任何难以撤销的决策。

产物： 扩展 docs/ARCHITECTURE.md 中的 ## Decision Log，记录 v1 明确不做的内容；扩展 docs/TECH-DEBT.md 中的 ## Debt Ledger（将暂缓的抽象作为有意承担的技术债逐项记录，并为每项注明重新审视的触发条件）。更新跟踪表。

完成标准： v1 范围已按投入意愿锁定；每项删除或暂缓的抽象都作为一行记录在 Decision Log 或 Debt Ledger 中，并注明重新审视的触发条件；没有为了节省时间而砍掉任何难以撤销的决策。

可选阶段

技能	添加时机	产物
team-topologies	系统将由多个团队共同负责，因此模块边界必须与团队边界一致（康威定律）	扩展 docs/OPERATIONS.md（## Team Structure）

可选阶段遵循相同的操作规则——像核心阶段一样加载并使用每个列出的技能；在添加条件首次满足时插入——本例中，是在第 2 阶段之后，此时必须与团队边界相对应的限界上下文已经建立。

常见错误

错误	修正方法
让框架成为架构本身	应用 Clean Architecture 的依赖规则（第 1 阶段）——框架调用指向内层；ORM 和请求类型应限制在最外环。
为无法证明必要的扩展性过度设计	先进行粗略的 QPS／存储容量计算（system-design，第 3 阶段）；一个带索引的数据库加缓存，通常足以支撑数年。
矫枉过正，陷入类泛滥	应用深模块规则（software-design-philosophy，第 5 阶段）——少数深模块胜过大量浅模块；只在真正易变的地方划分边界。
忽视数据库实际提供的一致性保证	检查默认隔离级别，并锁定易发生写偏斜的路径（ddia-systems，第 4 阶段）——写偏斜会通过所有单用户测试。
将弹性视为上线后的事	从一开始就设计超时、熔断器和分页（release-it，第 6 阶段）——依赖项响应缓慢且没有超时，会让一切陷入停顿。
混淆无需构建与草率构建	精简功能和推测性抽象（37signals-way，第 8 阶段），但绝不能删减少数难以逆转的决策。

完成本次旅程

根据项目调整投入：周末项目可侧重第 1 阶段的依赖规则、快速建立统一语言、为出站调用设置超时，以及第 8 阶段的精简范围原则——花几小时，就能省下几周。获得资金支持、正朝上线推进的团队则应贯穿整个技术栈，并在实际瓶颈和集成点出现时加入数据与弹性阶段。

退出检查清单——每项都对应一个产物：

• 每项难以逆转的决策（边界、上下文、数据／一致性）都已记录为 Decision Log 中的一行，并注明拒绝的替代方案（ARCHITECTURE.md）。
• 核心业务规则无需数据库、Web 或框架即可运行（ARCHITECTURE.md Layer Map 中没有违反依赖方向的情况）。
• 每个出站调用都有超时，关键调用有熔断器，所有列表均已分页（RELIABILITY.md Integration-Point Audit 已通过）。
• 一个 tracer-bullet 切片证明各边界端到端连通，并作为首个 CI 门禁（TESTING.md）。
• v1 范围已根据投入预期确定；推测性抽象已删减，或延后并设定触发条件（TECH-DEBT.md Debt Ledger）。

关闭跟踪表：每个阶段都标记为 done 或 skipped: reason，并将剩余的 Next Actions 记录到 ARCHITECTURE.md Decision Log 和 TECH-DEBT.md 中，确保没有遗漏。然后继续后续流程：如果该架构服务于一个仍需验证和构建的产品，请继续使用 create-app 技能；如果需要将现有原型改造成这一结构，请继续使用 improve-code-quality 技能。