architecture

架构技能

版本： 3.0 来源： 架构原则 + 项目结构配置

如何组织项目结构——包括逻辑结构（模块设计、依赖流向）和物理结构（文件夹布局、命名、特定类型的约定）。

问题

AI Agent 不会记得上次会话中把文件放在哪里。如果没有明确的结构，每次会话都会自行设计文件夹布局、模块边界和依赖模式，导致文件分散、循环导入，以及只有创建它的会话才理解的架构。这些标准定义了统一的结构，让每次会话都在相同的位置构建。

使用方式

• 构建者： 创建文件或文件夹前，先阅读 ## 构建者清单。按照与你的目标相匹配的项目类型配置执行。
• 重构者： 使用 ## 强制规则 查找结构违规。阅读说明部分，了解迁移指南。
• 两者： 说明部分是权威标准。清单和规则表是对同一内容的精简概述。

---

范围与边界

此技能涵盖： 模块设计、依赖流向、文件夹结构、命名约定以及特定项目类型的布局。

此技能不涵盖： 文件内部的代码质量（参见 code-quality）、文档标准（参见 documentation）或构建/部署配置。

与其他技能的关系：

• 与 code-quality（文件级约定）和 documentation（文档标准）协同使用
• 由 clean-team 的 :audit 命令使用（重点：structure）
• 供 clean-team、implement-team 和 diagnose-team Agent 参考

---

核心目标

目标： 小改动应局限在局部。

典型功能应只涉及 1-2 个模块，能快速交付，且无需在整个系统中协调修改。如果一个简单改动需要你在多个层中编辑 5 个以上的文件，这就表明设计存在问题。

---

核心原则

1. 明确优于魔法

优先选择易读的连接方式，而不是过度依赖约定的框架。别人阅读代码时，控制流应该一目了然。不要使用会隐藏依赖关系的 @AutoInject() 装饰器，而应使用显式的构造函数参数。

2. 边界神圣不可侵犯

模块只能通过契约（API、属性、事件）进行通信。不得触及其他模块的内部实现。应从模块的公共 API 导入，绝不直接从内部文件导入。

3. 数据归属清晰

每个模块拥有自己的架构/状态。其他模块通过 API 或属性读取数据，绝不直接访问。如果 OrderModule 需要用户数据，应调用 UserModule.getUserById()，而不是直接查询 users 表。

4. 优化重构体验

如果代码难以移动或重命名，这就表明设计存在问题。松耦合有助于安全重构。

---

三层结构

01-presentation/  →  02-logic/  →  03-data/

层级	职责	示例
表现层	用户看到并与之交互的内容	组件、页面、样式
逻辑层	构建方式、业务规则	服务、用例、验证
数据层	数据持久化方式、外部数据源	仓储、模型、适配器

有效的依赖流向

Presentation → Logic → Data ✅
Data → Logic ❌ (blocked)
Logic → Presentation ❌ (blocked)
Presentation → Data ❌ (blocked — no layer skipping)

---

模块边界

模块是一个内聚单元，拥有清晰的公共 API、隐藏的实现和明确的依赖关系。

模块规则

单一入口点： 每个模块通过索引文件公开其 API。外部导入必须经由该文件。

禁止循环依赖： 模块之间不能形成循环依赖。可通过提取共享代码、使用事件或引入接口来打破循环。

数据归属清晰： 每个模块独占其数据。跨模块访问数据必须通过 API，绝不能直接查询数据库。

耦合指南

耦合类型	是否可以？
类型导入	始终可以
通过公共 API 调用函数	通常可以
直接实例化	谨慎处理
共享可变状态	避免

完整详情： references/module-boundaries.md — 模块结构、边界规则、通信模式、耦合级别、重构指南

---

文件夹结构

组织良好的项目不只是整洁，更是一个让你无需询问“这个该放在哪里？”或“去哪里能找到那个？”的项目。结构本身就能回答这些问题。当文件夹与思考项目的方式相呼应时，导航就会变得直观，而不是一场搜索。你能在预期的位置一次就找到所需内容。

AI 参与时，这一点尤为重要。AI 不会在会话之间保留记忆，无法像人类队友那样随着时间推移熟悉项目布局。每次会话都是全新的。清晰、可预测的结构能让 AI 少花时间搜索，多做有用的工作。描述明确的文件夹名称、一致的约定和合理的分组，都是 AI 每次交互时都能免费读取的上下文。

目标：仅凭直觉，任何文件都应能在 2-3 步导航内找到。如果必须搜索，说明结构设计失败。

按层级内的功能组织

对于采用 3 层架构的 Web 项目，应在每个层级内按功能组织，不要将单个功能分散到全局的 models/、services/、controllers/ 目录中。

Within 02-logic/:
Prefer:                          Avoid:
02-logic/                        02-logic/
  users/                           models/
    user.model.ts                    user.model.ts
    user.service.ts                  order.model.ts
  orders/                          services/
    ...                              user.service.ts
                                     order.service.ts

按功能分组能让相关代码在每个层级内保持在一起。层级负责约束依赖流向（表示层 → 逻辑层 → 数据层），而功能文件夹负责确保每个层级内的内聚性。二者相辅相成，并不矛盾。

对于非 Web 项目（命令行工具、库、脚本），如果不采用 3 层架构，则在项目根目录下按功能分组。

通用结构原则

这些原则适用于所有项目，无论其类型如何。

命名一致性——为每类项目选定一种大小写命名约定，并在所有地方统一使用。所有组件使用 PascalCase，所有工具函数使用 camelCase，所有配置使用 kebab-case。一致的命名让内容更容易查找——了解约定后，你甚至可以在查看文件前预测文件名。

逻辑分组——相关文件放在一起。如果修改一个文件，很可能也要修改其他文件。默认将它们放在同一位置，仅在有明确好处时才拆分。判断是否应分组的方法是：“如果我正在处理 X，还需要打开哪些文件？”

合理的深度——从根目录到文件最多不超过 4 层。每一层嵌套都必须有存在的理由。如果某个文件夹只有一个子文件夹，而该子文件夹中只有一个文件，就将它们扁平化。深层嵌套不是组织有序，而是寻宝游戏。

清晰的入口点——首次打开项目的人应能在 10 秒内知道从何处开始。根目录的 README 说明项目是什么。主入口文件使用惯常名称（index、main、app）。顶层文件夹应能体现项目的整体内容。

整洁的根目录——项目根目录只应包含必须放在此处的内容：入口点、顶层配置，以及定义项目结构的文件夹。必须位于根目录的配置文件（.gitignore、package.json、tsconfig.json）不受此限；零散脚本、工具和一次性文件则不行。拿不准时，就把它移到更深的目录中。根目录代表项目给人的第一印象。

自描述名称——文件夹名称应描述其中的内容，而不是用途。formatters/、validators/、parsers/ 一目了然。utils/、helpers/、misc/ 则会沦为杂物堆。如果一个文件夹中有超过 10 个文件，且没有共同主题，就按文件的实际用途拆分。

---

项目类型配置

针对特定类型的文件夹结构、命名约定和警示信号。每种配置都可作为独立参考。

检测决策树

Does the project contain...

  ├─ package.json + .tsx/.jsx/.css/.html files?
  │  └─ YES → Load references/web.md
  │
  ├─ Assets/ + .cs scripts + .unity scene files?
  │  ├─ VRChat SDK present? (Packages/com.vrchat.*, VRCSDK3, UdonSharp)
  │  │  └─ YES → Load references/vrchat.md (overrides Unity)
  │  └─ No VRC SDK
  │     └─ Load references/unity.md
  │
  ├─ .blend files + texture images?
  │  └─ YES → Load references/blender.md
  │
  ├─ .tf files / cdk.json / template.yaml?
  │  └─ YES → Load references/data-iac.md
  │
  └─ None of the above?
     └─ Use Universal Structural Principles above

优先级规则： 当多个配置文件都匹配时，使用最具体的配置。VRChat 优先于 Unity。对于同时包含应用代码和 IaC 的项目，应用部分应使用应用配置，并参考基础设施部分的 data-iac。

可用配置

配置	参考文件	适用场景
Web（React/Node）	references/web.md	SPA、全栈应用、Node API、React 项目
Unity	references/unity.md	Unity 游戏、工具、非 VRChat Unity 项目
VRChat	references/vrchat.md	VRChat 世界和虚拟形象（扩展 Unity）
Blender	references/blender.md	3D 建模、贴图、渲染项目
Data/IaC（AWS）	references/data-iac.md	Terraform、CDK、CloudFormation 基础设施

使用方法

1. 使用上方决策树检测项目类型
2. 从 references/ 加载匹配的配置
3. 将实际结构与预期布局进行比较
4. 使用 assets/structure-evaluation-checklist.md 中的清单进行评估
5. 将偏差标记为发现项——优先处理红旗项

添加新配置

1. 按照标准模板创建 references/<type>.md：
   • 为什么这种结构很重要——问题、益处、忽略的代价
   • 检测——用于识别此项目类型的文件模式
   • 预期结构——带有原则注释的目录树
   • 命名约定——类型/约定/示例表格
   • 红旗项——3 列表格：标记 | 根本原因 | 修复方法
   • 重新考虑的时机——症状 → 问题 → 行动表格
2. 在上方的可用配置表中添加一行
3. 在检测决策树中添加一个分支
4. 在 assets/structure-evaluation-checklist.md 中添加特定类型的章节

---

模式选择

模式	适用场景
纯函数	无状态转换
带函数的模块	对相关函数进行分组
类	需要状态或依赖注入
工厂	复杂对象创建
仓储	数据访问抽象

默认选择简单方案： 函数 → 模块 → 类 → 模式

完整目录： references/design-patterns.md——工厂、建造者、适配器、外观、装饰器、策略、观察者、命令、仓储、结果类型

---

测试策略

类型	目的	范围	数量
单元测试	快速、确定性强、领域逻辑占比高	单个函数/组件	大量
集成测试	数据库、API、外部服务	模块边界	适量
端到端测试	仅覆盖关键用户路径	完整技术栈	极少

大量单元测试、适量集成测试、极少端到端测试。端到端测试泛滥会导致测试套件脆弱且运行缓慢。建议在 API 边界进行契约测试。

---

反模式

代码架构

反模式	症状	修复方法
上帝对象	超过 500 行、公开导出超过 10 项	拆分为内聚的子模块
贫血领域模型	只有 Getter/Setter，所有工作都由服务完成	将行为移至实体
散弹式修改	添加一个字段需要修改 5 个以上文件	改善封装

项目结构

反模式	症状	修复方法
根目录杂乱	项目根目录有 15 个以上文件，配置文件旁边散落着脚本	将所有非入口文件或非必需配置文件移入文件夹
巨型文件夹	一个文件夹中有 40 个以上文件	按领域、功能特性或用途分组
幽灵文件夹	文件夹为空，且没有明确用途	删除，除非它属于有意采用的模式
命名混乱	大小写风格混用：UserProfile.tsx、order-utils.ts、payment_service.py	为每种文件类型选定一种命名规范并严格执行
孤立文件	没有任何内容导入或引用的文件	确认未使用后删除
嵌套过深	需要经过 5 层以上文件夹才能找到单个文件	扁平化结构——层级应反映真实边界
镜像目录树	src/ 和 tests/ 结构完全相同	将单元测试与源代码放在一起；只有集成测试／E2E 测试才使用独立目录树
配置文件过多	根目录有 10 个以上配置文件	尽可能合并，并移至 config/

---

何时拆分

从模块化单体开始（单个可部署单元，内部边界清晰）。

仅在以下情况拆分为独立服务：

原因	示例
规模	某个部分需要独立扩展
团队	不同团队需要独立的部署周期
技术	某个组件需要不同的运行时／语言

不要为了“整洁”而拆分——这只会增加运维复杂性，却没有收益。

---

可观测性基础

结构化日志： 使用 JSON，而不是字符串拼接。包含上下文（{ userId, timestamp }），不要只记录消息（'User ' + userId + ' logged in'）。

关联 ID： 跟踪跨异步操作的请求。

错误边界： 捕获并报告错误，不要悄无声息地吞掉错误。

---

决策记录

对于重要的架构选择，记录：背景（问题）、决策（选择了什么）、备选方案（还考虑了什么）、后果（权衡）。

位置： Documentation/decisions/

模板： assets/decision-record-template.md

---

扩展原则

项目规模	关注重点
小型	北极星目标、危险信号
成长中	添加测试策略、可观测性
团队	添加决策记录、模块所有权

---

危险信号

看到以下情况时，请停下来重新考虑：

异味	问题	修复方法
shared/common/utils 成为杂物堆	所有权不明确，且会无限膨胀	移至所属模块，或创建专用软件包
跨模块直接导入	耦合紧密	使用 API、事件或属性
跨模块直接访问数据库	存在隐藏依赖	构建读取 API 或服务
在错误模块中添加“快捷辅助工具”	违反边界	移至正确的所属模块
框架魔法掩盖控制流	难以调试，也难以重构	明确呈现控制流
一个功能涉及 5 个以上互不相关的文件	分离不佳	重构边界

---

构建者检查清单

设计模块或文件夹结构前，请根据这些约束检查方案。构建者应在编写代码前阅读本节；重构者则应参考“强制规则”表和完整说明。

结构

• 3 层架构：01-presentation/ → 02-logic/ → 03-data/
• 不允许反向依赖（data → logic、logic → presentation）
• 不允许跳层（presentation → data）
• 从根目录到文件最多 4 层文件夹
• 根目录整洁——顶层仅保留入口文件和必需配置

模块

• 每个模块都有单一入口点（索引文件）
• 模块之间不存在循环依赖
• 每个模块拥有自己的数据——禁止跨模块直接访问数据库
• 在各层内按功能组织（而非使用全局 models/、services/ 文件夹）

设计

• 默认追求简洁：函数 → 模块 → 类 → 模式
• 小改动应局限在本地（一个功能涉及 1–2 个模块，而不是 5 个以上）
• 不要把内容一股脑放进 shared/common/utils
• 文件夹名称应描述其中的内容（而不是 helpers/、misc/）

---

强制规则

这些规则由 check.js（clean-team）确定性检查。更新这些标准时，也要更新相应的 check.js 规则以保持一致，反之亦然。

规则 ID	严重性	检查内容
tier-imports	错误	违反 01→02→03 依赖方向的导入
tier-structure	错误	Web 项目缺少或未完整采用三层文件夹结构

---

参考资料

• references/module-boundaries.md — 模块结构、边界规则、通信模式
• references/design-patterns.md — 工厂、仓储、适配器、策略、观察者等
• references/migration-patterns.md — 绞杀者无花果、抽象分支、并行实现
• references/web.md — Web（React/Node）项目结构配置
• references/unity.md — Unity 项目结构配置
• references/vrchat.md — VRChat 项目结构配置（扩展 Unity）
• references/blender.md — Blender 项目结构配置
• references/data-iac.md — Data/IaC（AWS）项目结构配置

资源文件

• assets/architecture-checklist.md — 完整的架构审查清单
• assets/structure-evaluation-checklist.md — 项目结构评估清单（通用版及各类型版）
• assets/decision-record-template.md — ADR 模板

脚本

• scripts/analyze_dependencies.py — 映射循环依赖并检测分层违规