00 - 总体架构设计

1. 体系定位

将 AI 辅助编程从"随意对话"提升为"工程化协作"。

本体系不是一份文档，而是一套可执行的基础设施，面向：

项目类型：全栈 Web 应用（React/Next.js + Node.js/Express/Nest）
使用者：个人开发者
核心追求：实操性优先，拒绝过度设计

2. 架构总图

┌─────────────────────────────────────────────────────────┐
│                    人（审查者）                           │
│  定方向 · 审输出 · 断风险 · 纠偏差 · 沉淀规则            │
└──────────────────────┬──────────────────────────────────┘
                       │ Prompt / 审批 / 打断
                       ▼
┌─────────────────────────────────────────────────────────┐
│                 Claude Code CLI（主代理）                 │
│                                                         │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐              │
│  │ CLAUDE.md│  │ Skills   │  │ Hooks    │              │
│  │ 规则引擎  │  │ 技能体系  │  │ 质量闸门  │              │
│  └──────────┘  └──────────┘  └──────────┘              │
│                                                         │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐              │
│  │SubAgents │  │ MCP      │  │ Commands │              │
│  │ 子代理    │  │ 外部工具  │  │ 自定义命令 │              │
│  └──────────┘  └──────────┘  └──────────┘              │
└─────────────────────────────────────────────────────────┘

3. 人机协作契约

架构图画的是"系统有什么"，但协作要先回答"谁负责什么"。

人的职责 — 意图与护栏

声明意图：写清楚要什么、为什么、什么不做（CLAUDE.md / Spec / PRD）
设定护栏：配置确定性防线，不依赖 AI 记忆（Hooks / 权限 / 安全基线）
关键节点介入：审查、验收、架构仲裁、不可逆操作批准

AI 的职责 — 理解与执行

意图不清时追问，不假设
护栏触发时停下报告，不绕过
上下文退化时主动提议 compact/clear，不硬撑
有能力自主拆解任务和调度子代理，不需要人逐步编排

协作节奏

意图越清晰，AI 越自主 — CLAUDE.md 写得好，Skills 和手动编排就用得少
护栏越完备，信任越充分 — Hooks 兜底了安全，人就可以放手让 AI 跑
多代理场景 — Lead 自主协调，人只审批关键节点和最终产出

4. 六大子系统及其关系

CLAUDE.md（规则层）
    │
    ├── 约束 ──→ Skills（执行层）
    │               │
    │               ├── 调度 ──→ SubAgents（并行执行）
    │               │               │
    │               │               └── 调用 ──→ MCP（工具层）
    │               │
    │               └── 触发 ──→ Commands（快捷入口）
    │
    └── 驱动 ──→ Hooks（自动化层）
                    │
                    └── 拦截/格式化/测试（确定性保障）

数据流方向：

CLAUDE.md → 向下约束所有子系统的行为
Skills/Commands → 向下调度 SubAgents 和 MCP
Hooks → 横向拦截所有工具调用
SubAgents → 只能被主代理调度，不能互相调用

5. 核心设计原则

5.1 五要素职责表

这是整套体系的决策核心。任何任务开始前，先对照此表判断用什么：

要素	职责	触发时机	举例
Prompt	推理、分析、创造性生成	需要"想一想"的任务	架构设计、Bug 分析、方案对比
Skill	固化的最佳实践模板	有成熟套路的重复性任务	代码审查、新功能开发、文档生成
SubAgent	半自主的专项能力	可并行的独立子任务	并行写码+测试+审查
MCP	工具连接与数据流转	需要访问外部系统	数据库查询、浏览器测试、文档检索
人工	方向、风险、最终批准	不可逆操作或重大权衡	技术选型、部署确认、合并决策

5.2 从四份参考文件提炼的五大原则

确定性越高，自动化程度越高 — Lint、格式化、测试这类 100% 确定性的任务，交给 Hooks 自动执行
能并行不串行 — 写码、测试、审查可以三个 SubAgent 同时跑
Skill 是经验的固化 — 每次写得好的 prompt 模式，都应沉淀为 Skill
人只做不可逆的决策 — 方向选择、风险承担、生产发布批准
MCP 是胶水不是大脑 — MCP 负责连接和数据搬运，不负责决策

5.3 执行韧性

体系的设计覆盖了"做什么"和"做得对不对"，但执行过程中的阻力吸收同样需要判断原则：

轻量交接：交接文档只写"下一步能直接执行的信息"，砍掉叙事性回顾。恢复上下文应在 30 秒内完成，超过说明交接文档太重
渐进执行：涉及外部 API 或批量数据的操作，先用 ≤5 条记录验证全流程再全量执行；连续失败 3 次即熔断报告，不盲目重试
约束前置：实现类会话的首条消息必须包含边界（技术栈、成本、时间、术语体系），不给 AI 自由发挥的空间

5.4 OODA 闭环

每个功能的开发遵循：

Observe（观察）→ Orient（分析）→ Decide（决策）→ Act（执行）
   读代码           出方案          人审批          写代码
   60% 时间                        40% 时间

时间分配：60% 在观察/分析（读代码、理解上下文、出方案），40% 在决策/执行。

5.5 上下文约束

CLAUDE.md 指令上限：100-150 条（系统提示已占约 50 条）
同时激活 MCP：不超过 5 个（每个都消耗上下文）
Skills 采用渐进式披露：启动时只加载元数据（约 100 token），按需拉取完整内容
上下文达 70% 时触发交接：/compact 或 /clear + 恢复

6. 分层配置架构

优先级从高到低：
1. 命令行参数              ← 运行时覆盖
2. .claude/settings.local.json  ← 个人设置（.gitignore）
3. .claude/settings.json        ← 项目设置（Git 追踪）
4. ~/.claude/settings.json      ← 全局设置

CLAUDE.md 加载顺序：
1. ~/.claude/CLAUDE.md          ← 全局编码偏好
2. 项目根/CLAUDE.md             ← 项目规则（Git 追踪）
3. 项目根/CLAUDE.local.md       ← 个人覆盖（.gitignore）
4. 子目录/CLAUDE.md             ← 模块上下文（进入时加载）

7. 完整项目目录结构

project-root/
├── CLAUDE.md                          # 项目规则（Git 追踪）
├── CLAUDE.local.md                    # 个人覆盖（.gitignore）
├── .claude/
│   ├── settings.json                  # 权限 + Hooks（Git 追踪）
│   ├── settings.local.json            # 个人设置（.gitignore）
│   ├── commands/                      # 自定义斜杠命令
│   │   ├── plan.md                    # /plan - 需求→方案
│   │   ├── review.md                  # /review - 代码审查
│   │   ├── new-feature.md             # /new-feature - 新功能开发
│   │   ├── debug.md                   # /debug - 问题诊断
│   │   ├── commit.md                  # /commit - 智能提交
│   │   └── doc.md                     # /doc - 文档更新
│   └── skills/                        # Skills 技能定义
│       └── code-standards/
│           └── SKILL.md
├── .mcp.json                          # MCP 服务器配置
├── docs/
│   ├── README.md                      # 文档导航索引
│   ├── features.md                    # 功能清单
│   ├── prd/                           # 产品需求文档
│   │   ├── goals.md
│   │   ├── user-scenarios.md
│   │   ├── scope.md
│   │   └── open-questions.md
│   ├── architecture/                  # 架构文档
│   │   ├── overview.md
│   │   ├── tech-stack.md
│   │   └── adr/                       # 架构决策记录
│   │       └── 001-template.md
│   ├── api/
│   │   └── api-spec.md
│   ├── data/
│   │   └── data-spec.md
│   ├── references/
│   │   ├── approved-deps.md           # 依赖白名单
│   │   └── resources.md
│   ├── product-spec.md                # 产品结构契约（/product-design 生成）
│   ├── design-spec.md                 # 设计规范契约（/product-design 生成）
│   └── templates/                     # 模板文件（体系提供）
│       ├── product-spec-template.md
│       └── design-spec-template.md
└── .github/
    └── workflows/
        └── ci.yml                     # CI/CD

相比 V3.0 手册精简掉的：

specs/ — 个人项目不需要独立规范文件，需求写在 prompt 里
docs/checkpoints/ — 用 git commit message 替代推理留痕
.claude/agents/ — 进阶用户可创建自定义子代理（详见 03 篇 §3）
.claude/work/ — 不需要工作流状态持久化

8. 渐进式采用路径

不需要一次配好所有模块。推荐的启动顺序：

Level 0（5分钟）：CLAUDE.md + settings.json 基础权限
    ↓ 用几天，感受效果
Level 1（15分钟）：+ 3 个核心 Commands（/plan, /review, /commit）
    ↓ 形成习惯
Level 2（15分钟）：+ Hooks（自动格式化 + 安全防火墙）
    ↓ 质量闸门自动化
Level 3（15分钟）：+ MCP（按需接入 2-3 个）
    ↓ 外部工具集成
Level 4（按需）：+ Skills + 更多 Commands

9. 成本控制策略

子代理每个都开独立上下文窗口，需要注意成本：

子代理默认使用 Sonnet（设置 CLAUDE_CODE_SUBAGENT_MODEL=sonnet）
主会话使用 Opus 保持推理质量
简单的代码搜索用 Explore Agent（内置，轻量）
只有并行独立任务时才派发多个子代理
研究类任务用后台子代理（run_in_background），不阻塞主线程

10. 体系演进方向

10.1 成熟度信号

第 8 节的渐进式采用路径描述了"何时加什么"。本节补充**"什么信号说明你该升级"**：

当前水平	升级信号	下一步
Level 0	每次都在 prompt 里重复相同的编码规范	→ Level 1：把重复 prompt 沉淀为 Command
Level 1	频繁手动运行 lint/format/测试	→ Level 2：用 Hooks 自动化
Level 2	需要查外部数据（数据库、文档站）但每次手动复制	→ Level 3：接入 MCP
Level 3	Command 的指令越来越复杂，超过 50 行	→ Level 4：升级为 Skill，利用渐进式披露

反向信号（说明过度配置了）：

某个 Skill 连续 4 周没人调用 → 移除
Hook 频繁误拦正常操作 → 放宽或移除
同时激活的 MCP > 3 个但大部分闲置 → 精简

10.2 跨项目知识迁移

当你维护多个项目时，规则的归属决策：

全局 ~/.claude/CLAUDE.md（所有项目共享）：
  - 交互偏好（语言、commit 格式）
  - 通用工作流（先读后写、契约先行）
  - 不含任何特定技术栈的规则

项目 CLAUDE.md（项目独有）：
  - 技术栈规范（框架版本、ORM 用法）
  - 模块边界和架构约束
  - 项目特有的常见陷阱

迁移判断：如果同一条规则在 3 个项目中重复出现 → 提升到全局。

10.3 战术 vs 战略的优先级

当"快速出功能"和"长期可维护"冲突时的决策框架：

不可逆操作 → 永远选战略（数据库 schema、公开 API、安全边界）
可逆操作   → 允许先选战术，但记录技术债

记录方式：在代码中留 TODO(debt) 注释 + 在 CLAUDE.md 常见陷阱中标注
清理节奏：每月体检时审查技术债清单

核心原则：速度优先但债务可追踪。 没有记录的技术债才是真正的风险。

10.4 外部进化

体系的进化不仅来自内部积累（doc-08 闭环），还需要从外部世界吸收养分。20-体系外部进化机制定义了五种标准化输入通道（用户喂文章、定期搜索、项目反哺、竞品对标、版本追踪），通过 /absorb Skill 执行结构化评估和融合。

11. 文档维护原则：判断写死，清单写活

体系的不可替代价值在判断力——什么时候该用什么、为什么、哪些坑要避开。Claude Code 官方文档在事件列表、配置语法、API 参数上永远比我们更准确更及时，我们不跟它赛跑。

判断层（稳定）：决策框架、设计原则、选型策略、反模式。只有范式级变化才触发更新。这是体系的护城河。

参考层（易变）：事件列表、配置语法、定价数据。标注时效和来源，链接官方文档。读者知道去哪里获取最新信息即可。

单一数据源：每个事实只在一个文档中定义，其他文档引用。避免多处重复导致的不一致。

维护判断：Claude Code 发布新功能时，先问"这改变了我们的哪个决策判断？"——如果只是新增了一个事件或参数，不需要更新文档；如果改变了"什么时候该用什么"的答案，才需要更新判断层。

00 - 总体架构设计 ​

1. 体系定位 ​

2. 架构总图 ​

3. 人机协作契约 ​

4. 六大子系统及其关系 ​

5. 核心设计原则 ​

5.1 五要素职责表 ​

5.2 从四份参考文件提炼的五大原则 ​

5.3 执行韧性 ​

5.4 OODA 闭环 ​

5.5 上下文约束 ​

6. 分层配置架构 ​

7. 完整项目目录结构 ​

8. 渐进式采用路径 ​

9. 成本控制策略 ​

10. 体系演进方向 ​

10.1 成熟度信号 ​

10.2 跨项目知识迁移 ​

10.3 战术 vs 战略的优先级 ​

10.4 外部进化 ​

11. 文档维护原则：判断写死，清单写活 ​