define-architecture

定义架构

为 TypeScript 全栈应用定义持久、易于调整的架构默认规范；产出可强制执行的架构说明。

• **是：**文件夹结构、模块契约、中间件管线、前后端边界；架构说明；结合领域知识深化现有代码库；适合 Agent 的代码库护栏。
• **不是：**搭建新仓库（Next.js turborepo 使用 scaffold-nextjs，TypeScript CLI 使用 scaffold-cli）、多租户领域／隔离／路由（multi-tenant-architecture），或审查本地 diff 的结构（pr-reviewer）。

目录

• 工作流与参考资料
• 搭建工作流（新代码库）
• 采用工作流（现有代码库）
• 验证循环
• 输出模板
• 相关技能
• 注意事项

工作流与参考资料

跟踪此清单：

Architecture progress:
- [ ] Step 1: Pick workflow (new codebase: Setup; existing: Adoption)
- [ ] Step 2: Run it end to end
- [ ] Step 3: Write the brief (Output template)
- [ ] Step 4: Run Validation loop, record results in brief
- [ ] Step 5: Fix failed checks, re-run loop

仅在符合条件时加载参考资料：

参考资料	阅读时机
references/stack-defaults.md	选择库、工具或部署目标时
references/api-design.md	设计端点、模块契约或请求上下文时；审查 API 表面变更时
references/distributed-correctness.md	设计会调用外部系统、处理 Webhook、重试、需要审计跟踪或涉及资金流转（账单、额度、付款）的流程时
references/deepening-existing.md	运行采用工作流时（领域映射、机会模式、输出模板）
references/craftsmanship.md	编写团队约定、测试或质量标准章节时
references/agent-friendly-codebase.md	为编码 Agent 准备代码库时：护栏工具、不变量逐步收紧、遗留标记、生成的契约、验证层级
references/shipping-practices.md	编写发布与回滚章节时

设置工作流（新代码库）

1. 先明确约束：产品范围、团队规模、合规性／安全性、预期规模、部署目标、必需集成以及质量标准。
2. 选择仓库结构：
   • 使用 apps/ 存放可部署的部分（api、web、admin）。
   • 使用 packages/ 存放共享库（shared、ui、icons、auth、proto）。
3. 定义后端模块契约，并为每个模块注明强制执行方式（lint 边界规则或类型检查）：
   • handler：仅负责传输。
   • service：负责业务编排。
   • dao：仅负责数据库访问。
   • mapper：负责 DB／proto／领域模型之间的转换。
   • constants 和 types：定义模块本地契约。
4. 定义请求上下文和中间件：
   • 在由 AsyncLocalStorage 支持的 RequestContext 中携带 tenantId、userId 和 traceId，并在每个入口（RPC、HTTP、作业、CLI）中初始化；通过 getContext() 读取；绝不要通过业务函数传递 ctx 参数。实现见 references/api-design.md。
   • 注册时要求为每个 RPC 方法明确指定身份验证策略；未指定策略的方法会导致注册失败，绝不默认开放访问。
   • 将身份验证、日志记录、错误处理和上下文放在共享中间件中，而不是各个处理器代码中。
5. 定义前端边界：
   • 默认使用 Server Components；只有需要交互性的叶子组件才添加 "use client"。
   • 服务端状态使用 TanStack/Connect Query；客户端状态使用组件状态；仅当跨组件的客户端状态两者都不适用时才使用 MobX。
   • 每份数据只能有一个所有者。绝不要将服务端数据镜像到 useState，也不要用 useEffect 同步两个存储；这两种做法都表明数据归属不明确。
6. 测试与发布：
   • 单元测试不依赖数据库；集成测试／E2E 测试并行运行，并动态生成 ID，确保各次运行不会在测试固件上发生冲突。
   • 以小型、完整且可回退的垂直切片发布，并为每项变更制定回滚计划。
   • 只有在可靠性、错误路径、可观测性和面向用户的状态都得到覆盖后，切片才算完成；不要将这些工作推迟到之后的润色阶段。
7. Agent 护栏：根据 references/agent-friendly-codebase.md，将死代码、重复代码、边界和文件大小检查接入提交前检查和 CI。

采用工作流（现有代码库）

目标：深入理解领域，而非重写。加载 references/deepening-existing.md，了解分析方法、机会模式和输出模板。

1. 梳理领域语言和决策。 如果存在 CONTEXT.md、docs/adr/ 或本地同类文件，先阅读，然后查看代码，了解团队对实体、操作和限界上下文的命名。记录差异（一个概念，三种名称；或一个名称，三种概念）。
2. 寻找深化机会。 查找贫血概念、浅层模块、边界泄漏、命名差异、重复概念、基本类型偏执、逻辑放错位置，以及被迫越过公共接口的测试。逐项记录文件路径，切勿只写模糊的问题描述。
3. 按杠杆效应排序。 优先选择通过删除测试、能明确局部化未来变更、低变动频率、满足当前需求且具备可行测试接缝的机会。在设计目标接口之前先为候选项排序；舍弃推测性的清理工作。
4. 先迁移一个垂直切片。 先通过一个切片端到端地验证杠杆效应最高的改动，再进行泛化。
5. 添加护栏。 通过 lint、类型或测试检查强制执行新边界，防止其退化，然后逐个模块推广。针对 Agent 的护栏（死代码、重复代码、遗留标记、文件大小上限），请加载 references/agent-friendly-codebase.md。

验证循环

定稿前运行；将结果记录在简报中（开放风险）。每项检查都需要证据；“看起来一致”不算通过。

1. 一致性： 所有服务中的命名、模块边界和中间件规则保持一致。证据：矛盾扫描结果为零。
2. 可执行性： 每项契约都注明其 lint 规则、类型检查或测试。证据：每项契约都有对应的执行列或说明。
3. 可运维性： 每个可部署表面都有可观测性、健康检查和回滚路径。证据：发布章节逐一列出这些内容。
4. 质量门禁（仅在代码变更时，例如 Adoption 切片）： 运行仓库的 lint、类型检查和针对性测试（npm run lint、npm run check-types、npm run test --workspace=<pkg> 或等效命令）。证据：通过的输出。

失败时：修复简报或约定，然后重新运行验证循环。

输出模板

使用以下结构：

# Architecture brief

## Context and constraints
## Repo shape
## Backend module contracts
## Request context and middleware policy
## Frontend boundaries
## Testing strategy
## Quality bar and surface-area budget
## Rollout and rollback plan
## Open risks and follow-ups

相关技能

• scaffold-nextjs 或 scaffold-cli：简报达成一致后，用于搭建仓库。
• multi-tenant-architecture：用于租户识别、隔离和领域策略。
• pr-reviewer：实现后用于审查本地差异。
• planning：将 Adoption 机会转化为实施计划，然后对其进行压力测试。
• agents-md：审计和重构 AGENTS.md 文件本身；此技能会判断哪些内容应放入工具中。
• tidy：限定于差异范围的清理；references/agent-friendly-codebase.md 介绍了仓库级防护措施的设置，以控制这些清理的范围。

易踩问题

• 团队人数少于 5 人时，不要默认采用微服务：每个服务都会增加一条部署流水线、契约版本管理和 on-call 负担。先从模块化单体仓库开始；只有当团队或规模压力证明某个边界合理时再拆分。
• 不要把应用级依赖放进单体仓库根目录的 package.json：依赖提升会掩盖缺失的声明，导致应用在本地能构建，单独部署时却失败。每个应用都应自行管理依赖。
• 不要定义没有执行机制的模块契约（handler/service/dao）：没有执行机制的契约会在第一个截止日期到来时失效。写下契约的当天就添加导入边界 lint 规则（例如 dao 不得导入 handler）。
• 不要通过在业务函数间传递 ctx 参数来替代 AsyncLocalStorage：每个函数签名都会变长，之后添加一个字段就要改动数百个调用点。
• 不要在页面或布局级别放置 "use client"：这会将整个子树转为客户端渲染，并失去流式传输和直接访问服务器数据的能力。应将其下推到叶节点。
• Adoption 阶段不要提议大爆炸式重写：先迁移一个垂直切片，验证后再推广。
• 不要过早提取到 packages/：等到至少 3 个应用需要相同代码时再提取；过早创建共享包只会无谓地耦合发布周期。
• 不要在没有为每项变更制定回滚计划的情况下定稿简报：不可逆的决策在发布前必须有记录在案的备用方案。
• 不要在没有 outbox（或 CDC）的情况下同时写入数据库和队列/webhook：一方提交、另一方失败时，就会悄无声息地丢失或凭空生成通知。请参阅 references/distributed-correctness.md。
• 不要通过构造方式强制执行可能由外部因素触发的约束（无符号类型、硬 CHECK）：当外部世界强制产生该状态时，系统会崩溃或截断，而不是记录该状态。应将其表示出来、事后检测，并明确恢复。
• 不要在 AGENTS.md 中编写 linter 能确定性执行的规则：提示词规则会在上下文压力下逐渐失效；而 pre-commit 和 CI 中的退出码不会。
• 不要让未标记的旧代码与当前模式并存：Agent 会进行 grep，先找到旧端点，然后基于它继续构建。应添加易于 grep 的 LEGACY 注释，或将其删除（请参阅 references/agent-friendly-codebase.md）。