📒 学霸笔记：16｜顶层设计：构建你的 AI 原生开发“驾驶舱”

Top Student Notes: 16 | Top-Level Design: Build Your AI-Native Development “Cockpit”

课程 / Course: AI 原生开发工作流实战 / AI-Native Development Workflow in Practice
讲师 / Instructor: Tony Bai
章节 / Chapter: 16
主题 / Topic: AI 协作框架、项目级与用户级布局、.claude/、specs/、CLAUDE.md、constitution.md、共享配置、个人覆盖、AI 原生开发驾驶舱

一、这一讲在解决什么问题？

What Problem Does This Lecture Solve?

从第 1 讲到第 15 讲，我们已经陆续学了很多 Claude Code 的能力：

• @ / !：上下文与命令调用
• CLAUDE.md：项目长期记忆
• constitution.md：项目原则与约束
• Slash Commands：标准流程封装
• Hooks：事件驱动自动化
• MCP：连接外部系统
• Skills：专家能力封装
• Subagents：多智能体分工
• Checkpointing：安全回滚
• Headless：脚本与 CI 集成

这些能力单独看都很强，但问题是：

如果没有统一的组织方式，这些能力只是“零散招式”，不是一套稳定可复用的“体系”。

这一讲要解决的核心矛盾

你现在已经有了很多“武器”，但如果没有一个统一框架，实际工作里会发生什么？

• 开发者 A 把命令放在自己的目录里
• 开发者 B 有另一套 Hook 逻辑
• 开发者 C 用自己的提示词风格
• 每个人机器上的 Claude 行为都不一致
• 团队经验无法沉淀
• 新人不知道该用哪个命令、哪个 Skill、哪个流程
• AI 在不同环境下像不同“人”

这就是 Tony 说的：

从“零散的游击战”走向“体系化作战”的必要性。

所以这一讲的本质是什么？

这一讲不是在教某个新功能，而是在教你：

如何为团队和项目设计一套 AI 协作的基础设施框架。

也就是：

• 如何组织 Claude 相关资产
• 如何划分团队共享 vs 个人专属
• 如何让能力可复用、可扩展、可版本化
• 如何让 AI 从“每次临时搭班子”变成“长期入职团队成员”

二、本讲核心结论

Core Conclusion of This Lecture

一句话总结

AI 原生开发不是把若干 Claude Code 功能拼在一起，而是先设计一套项目级 + 用户级的协作框架，让规则、能力、自动化和知识资产都能被系统性组织、继承和演进。

三、为什么一开始不直接写代码？

Why Don’t We Start Coding Immediately?

这是这一讲最关键的思维切换。

很多人会想：

• 工具都学完了
• 项目都准备好了
• 为什么不直接开始需求、设计、编码？

Tony 的答案是：

因为如果没有统一驾驶舱，后面的实战只会越做越乱。

没有框架时，AI 协作是什么样？

是“人和 AI 的私人临时合作”。

特点是：

• 依赖个人习惯
• 高度不可迁移
• 没有统一入口
• 没有统一规则
• 没有共享能力
• 没有团队沉淀

这是一种：

游击战模式

有框架时，AI 协作是什么样？

是“项目和团队级别的标准化协作平台”。

特点是：

• 同一项目中任何人拉下代码都能直接用
• AI 的行为有统一世界观
• 团队 SOP 被沉淀成命令、技能、自动化规则
• 人换了，项目的 AI 协作基础设施还在
• 新人能快速进入团队协作节奏

这是一种：

体系作战模式

四、这一讲提出的“驾驶舱”是什么？

What Is the “Cockpit” Proposed in This Lecture?

Tony 用“驾驶舱”这个词特别好，因为它不是单个零件，而是一整套协同系统。

驾驶舱里不是只有方向盘，还包括：

• 仪表盘
• 导航
• 油门刹车
• 自动驾驶
• 告警系统
• 操作面板

对应到 AI 原生开发里，驾驶舱就是：

一套能够统一承载 AI 规则、能力、流程、上下文、自动化与扩展点的工程布局。

五、这个驾驶舱的三大核心价值

The Three Core Values of This AI Cockpit

Tony 明确总结了三点，这里非常值得背。

1. 沉淀经验

Preserve Team Knowledge

团队里很多高价值经验，过去往往存在于：

• 老员工脑子里
• Wiki 里
• 零散文档里
• 口口相传中

有了框架之后，这些经验可以被沉淀为：

• Slash Commands
• Skills
• Subagents
• Hooks
• CLAUDE.md
• constitution.md

也就是说：

知识从“文档说明”升级为“AI 可执行资产”。

2. 统一标准

Standardize Team Behavior

过去团队规范常常靠：

• 约定
• code review
• 老员工提醒
• README 文档
• 大家自觉

但这些都不稳定。

框架建立后：

• 共享 settings.json
• 项目 constitution.md
• 项目 CLAUDE.md
• 统一 Hook
• 统一 Skills / Agents

都可以把团队规范“固化”下来。

所以它的作用不是“提醒规范”，而是：

让规范成为默认运行环境的一部分。

3. 赋能团队

Empower the Team

框架会大大降低上手门槛。

对于新人来说：

• 不必自己摸索命令
• 不必先读完全部文档
• 不必靠口头传承理解流程

AI 会在框架加持下：

• 给出符合团队风格的建议
• 按项目规则思考
• 自动应用规范
• 引导新人进入正确工作流

所以这是一种真正的：

团队级生产力放大器

六、这一讲的设计原则

Design Principles Introduced in This Lecture

Tony 提出了四个现代工程化原则，这其实是整个实战篇的设计基座。

1. 模块化

Modularity

每一种 AI 能力应该有独立位置和边界，例如：

• commands
• skills
• agents
• hooks

这和软件工程里的模块化思想完全一致。

2. 分层

Layering

要清楚区分：

• 项目级
• 用户级
• 团队共享
• 个人专属

否则所有东西混在一起会很快失控。

3. 可共享

Shareability

项目框架中的核心资产必须可以：

• 提交到 Git
• 被团队共享
• 被审查
• 被演进

4. 可扩展

Extensibility

框架不是一次性搭完就结束，而应该可以持续添加：

• 新命令
• 新 Skill
• 新 Agent
• 新 Hook
• 新规则

所以它必须是“活的”。

七、这套蓝图最核心的结构：项目级 vs 用户级

The Most Important Architectural Split: Project-Level vs User-Level

这一讲最重要的结构设计，就是区分两个层级：

1. 项目级框架（Project Layout）

位置：

./

特点：

• 属于当前项目
• 属于团队共享资产
• 应提交到 Git
• 用来定义项目规则与团队能力

它回答的是：

这个项目中的所有人和 AI，应该如何协作？

2. 用户级框架（User Layout）

位置：

~/

特点：

• 属于个人
• 跨项目复用
• 不提交到项目仓库
• 用来定义个人风格与私人工具

它回答的是：

这个开发者在所有项目中的个人默认工作方式是什么？

学霸理解

这套分层特别像现代配置系统的经典结构：

• 团队级配置 = 项目规则
• 个人级配置 = 用户偏好
• 最终运行环境 = 两者合并后的结果

八、Claude Code 在这里扮演什么角色？

What Role Does Claude Code Play in This Layout?

Claude Code 会在启动时把：

• 用户级配置
• 项目级配置

进行：

合并与覆盖

从而生成最终运行态。

所以这个框架不是死的目录树，而是：

Claude 启动时动态装配出的项目级 AI 运行环境。

九、Git 管理策略的重要性

Why Git Strategy Matters Here

Tony 特别提到 .gitignore，这不是小事，而是框架设计的一部分。

为什么要忽略 .claude/settings.local.json？

因为它属于：

• 个人本地覆盖
• 私人偏好
• 不应该污染团队基线

这样设计的好处是：

• 团队共享 settings.json
• 个人覆盖 settings.local.json
• 团队统一性和个人自由度并存

学霸理解

这其实是一个非常典型的工程配置设计：

共享基线进 Git，个人覆盖留本地。

十、项目级框架的核心：./.claude/

The Core of the Project-Level Framework: ./.claude/

Tony 把这个目录称为：

AI 能力的引擎室

这个比喻非常准确。

因为这里装的是：

• 命令系统
• 技能系统
• 专家系统
• 自动化系统
• 配置系统

十一、commands/：团队 SOP 的入口

commands/: The Entry Point for Team SOPs

这里放的是团队的 Slash Commands。

本质上是：

标准操作流程（SOP）的命令化封装

例如：

• /review-go-code
• /release-checklist
• /bug-triage

它的价值不只是方便，而是：

把“最佳实践”从文档说明变成可一键执行的工作流。

十二、skills/：团队领域知识库

skills/: The Team’s Domain Knowledge Base

这里放的是项目级 Skills。

本质上是：

团队专家知识的可发现、可加载版本

例如：

• go-code-reviewer
• api-design-guidelines
• database-migration-reviewer

它的价值是让 AI 不只是通用助手，而是：

• 懂这个项目
• 懂这个业务
• 懂这个团队的设计哲学

十三、agents/：团队的虚拟专家团队

agents/: The Team’s Virtual Expert Team

这里放的是项目级 Subagents。

本质上是：

团队定义好的专家角色集合

例如：

• go-code-security-reviewer
• performance-optimizer
• test-coverage-enhancer

它代表：

• 复杂任务的专家分工
• 多智能体协作体系
• 团队对“谁该做什么”的组织设计

十四、hooks/：团队自动化规则落地点

hooks/: Where Team Automation Rules Live

这里放的是 Hook 相关脚本与逻辑。

本质上是：

团队质量门禁与自动收尾动作的实现容器

例如：

• gofmt 自动格式化
• lint 自动执行
• 禁止危险操作
• 修改后触发校验

这样，规范就不再只是“请记得做”，而是：

由系统自动做

十五、settings.json vs settings.local.json

settings.json vs settings.local.json

这是这一讲很关键的一组配置设计。

settings.json

团队共享基线配置。

里面适合放：

• 权限策略
• 默认模型
• 共享 Hook
• 安全边界
• 团队统一行为

settings.local.json

个人本地覆盖配置，不进 Git。

里面适合放：

• 个人主题
• 个人偏好
• 局部权限调整
• 不影响团队的私有配置

学霸理解

这相当于：

• settings.json = 团队契约
• settings.local.json = 个体微调

十六、./specs/：规范驱动开发的作战指挥室

./specs/: The Command Room for Spec-Driven Development

这一部分和前面讲过的 SDD（规范驱动开发）完全接上了。

Tony 这里强调：

• specs/ 不只是放文档
• 它是从需求到计划到任务的标准化容器

例如每个 feature 下：

• spec.md
• plan.md
• tasks.md

所以这里的价值是：

把需求、设计、执行拆解的过程结构化，并与 AI 工作流直接对接。

十七、CLAUDE.md 与 constitution.md：世界观双核心

CLAUDE.md and constitution.md: The Two Cores of AI Worldview

这是这一讲最重要的“灵魂注入”部分。

constitution.md

是项目的根本大法。

它定义的是：

• 不可动摇的原则
• 架构哲学
• 设计边界
• 不可协商的开发铁律

例如：

• 简单性优先
• 测试先行
• 显式错误处理
• 无全局状态

所以它回答的是：

在这个项目里，什么是绝对不能违反的？

CLAUDE.md

是项目操作手册。

它定义的是：

• 具体工作方式
• 技术栈
• 构建命令
• 协作规则
• 任务执行 SOP

所以它回答的是：

在这个项目里，具体应该怎么做事？

学霸理解

可以这样背：

• constitution.md = 为什么与不许越线
• CLAUDE.md = 怎么做与怎么协作

十八、用户级框架：你的私人武器库

User-Level Framework: Your Personal Arsenal

项目级保证一致性，用户级则保证个体效率。

Tony 对 ~/.claude/ 的定位是：

你跨所有项目的全局 AI 配置中心

里面适合放什么？

1. CLAUDE.md

你的个人协作风格，例如：

• 喜欢多举例
• 喜欢先总结再展开
• 喜欢输出带注释代码

2. commands/

跨项目通用命令，如：

• 翻译
• 写周报
• 生成 commit message

3. skills/

个人积累的通用专家能力

4. agents/

个人常用专家

5. settings.json

你的个人默认模型、默认权限、全局偏好

学霸理解

项目级是“公司配发的战车”，
用户级是“你自己加装的私人外挂”。

十九、这个框架如何真正支撑工作流？

How Does This Framework Actually Support the Workflow?

Tony 用“PR 审查”举了一个非常好的端到端例子。

这段例子特别重要，因为它展示了：

框架不是摆设，而是会在实际任务里被动态激活。

场景推演核心流程

你在 PR 评论区说：

@claude review this PR

然后背后会发生什么？

第一步：加载配置与记忆

Claude 启动时加载：

• 用户级 settings
• 项目级 settings
• 用户级 CLAUDE.md
• 项目 constitution.md
• 项目 CLAUDE.md

AI 的“世界观”瞬间成形。

第二步：匹配能力

Claude 分析任务“review this PR”，发现：

• 有适合的 Skill
• 可能有适合的 Agent

于是自主调用最合适的能力。

第三步：按规则执行

如果 Skill 规定：

• 必须先阅读 constitution.md
• 再根据原则审查代码

AI 会照做。

第四步：自动化收尾

如果 AI 修改了文件：

• PostToolUse Hook 被触发
• 自动执行 gofmt

第五步：输出符合团队规范的结果

最终你看到的不是原始 AI 随机表现，而是：

• 符合宪法
• 符合项目操作手册
• 调用了适配能力
• 经过自动化收尾

的一套标准化结果。

学霸理解

所以这个框架的真正作用是：

把一次简单的用户意图，转译成一整套有规则、有能力、有自动化的执行链。

二十、这一讲的实战部分到底在做什么？

What Does the Hands-On Setup in This Lecture Actually Achieve?

从表面看，这一讲后半部分像是在：

• 建目录
• 写 .gitignore
• 填几个配置文件
• 初始化 Git

但本质上其实是在做：

给项目建立 AI 基础设施底座。

这一步非常像什么？

非常像项目初始化时做这些事情：

• 配 go.mod
• 配 Makefile
• 配 CI
• 配 Dockerfile
• 配 lint
• 配项目目录结构

也就是说：

AI 协作框架在 AI 原生开发里，已经和传统工程基础设施一样重要。

二十一、为什么 constitution.md 要先写？

Why Write constitution.md First?

因为这是项目的价值观与边界定义。

如果没有它，AI 的行为虽然能“做事”，但未必“按团队哲学做事”。

Tony 给的示例宪法非常典型，包括：

• 简单性优先
• TDD
• 表格驱动测试
• 显式错误处理
• 无全局变量

这意味着 AI 一开始就不是自由发挥，而是：

带着项目开发哲学入场。

二十二、为什么 CLAUDE.md 也必须初始化？

Why Must CLAUDE.md Also Be Initialized?

因为宪法解决“原则”，但不解决“流程细节”。

例如：

• 技术栈是什么
• 用什么构建
• 命令怎么跑
• commit message 怎么写
• 添加功能时先做什么

这些都应该写进 CLAUDE.md。

所以：

• constitution.md 让 AI 不越线
• CLAUDE.md 让 AI 不走偏

二十三、settings.json 为什么是“安全护栏”？

Why Is settings.json Called the “Safety Guardrail”?

因为它规定了 AI 的行动边界，比如：

• 什么可以默认做
• 什么必须 Ask
• 什么直接 Deny

Tony 给的例子非常像一套团队级权限基线。

其设计思想是什么？

默认模式：plan

先计划，不乱动

allow

允许的低风险动作

ask

需要审批的高影响动作

deny

禁止访问的敏感区域或危险命令

学霸理解

这让项目在第一天就具备：

• 安全
• 可审计
• 可协作

而不是等出问题再补规则。

二十四、为什么要初始化用户级框架？

Why Initialize the User-Level Framework Too?

因为完整体验需要两层框架同时存在：

• 项目级提供团队标准
• 用户级提供个人跨项目能力

这样你在任意项目里都能同时拥有：

• 团队统一环境
• 自己的私有增强

二十五、为什么一定要纳入版本控制？

Why Must This Framework Be Put Under Version Control?

这是这一讲最后一个非常重要的工程观念。

Tony 强调：

这些不是“本地小配置”，而是项目核心资产。

为什么必须进 Git？

1. 团队共享

每个人 clone 下来都是同一套 AI 环境

2. 可追踪

框架的变更可回溯

3. 可审查

高风险变更也走 PR

4. 可演进

AI 协作方式和代码一样被持续优化

学霸理解

从这一步开始，AI 协作方式不再是个人技巧，而是：

项目基础设施的一部分。

二十六、这一讲真正的认知升级

The Real Cognitive Upgrade in This Lecture

这一讲的最大升级，不是会创建这些目录，而是完成了下面这次思维变化：

以前的思维

• Claude 是个工具
• 功能很多
• 需要时拿来用一下

现在的思维

• Claude 协作需要架构设计
• AI 能力需要资产化组织
• 团队规则要进入运行环境
• AI 系统也需要基础设施层

换句话说

你不再只是：

• 会用 Claude 的开发者

而开始成为：

AI 协作系统的设计者

二十七、这一讲和 09-15 讲是什么关系？

How Does This Lecture Connect to Lessons 09–15?

这一讲其实就是把前面所有能力“安家”。

可以这样理解：

• 09-15 讲：学会有哪些零件
• 16 讲：学会如何把这些零件装进一台车里

对应关系

安全

• 09 讲的 permissions → settings.json

自动化

• 11 讲的 hooks → .claude/hooks/

外部扩展

• 12 讲的 MCP → 后续可纳入协作框架

专家能力

• 13 讲的 Skills → .claude/skills/

多智能体

• 14 讲的 Agents → .claude/agents/

自动化接口

• 15 讲的 Headless → 未来接入 CI / Script

上下文记忆

• 06-07 讲的 CLAUDE.md / constitution.md → 项目根目录

学霸理解

16 讲就是：

前面所有能力的系统集成设计图。

二十八、本讲知识结构图

Knowledge Structure of This Lecture

前面学了很多 Claude Code 能力
        ↓
如果没有统一组织方式
这些能力只是零散招式
        ↓
需要 AI 协作框架
        ↓
目标：从游击战升级为体系作战
        ↓
设计原则
├── 模块化
├── 分层
├── 可共享
└── 可扩展
        ↓
核心分层
├── 项目级框架（团队共享）
└── 用户级框架（个人专属）
        ↓
项目级核心组成
├── .claude/
│   ├── commands/
│   ├── skills/
│   ├── agents/
│   ├── hooks/
│   └── settings.json
├── specs/
├── CLAUDE.md
└── constitution.md
        ↓
用户级核心组成
└── ~/.claude/
        ↓
Claude 启动时加载并合并
        ↓
形成统一 AI 运行环境
        ↓
最终目标
让 AI 成为真正“入职项目”的团队成员

二十九、学霸速记表

Quick Revision Table

三十、学霸自检题

Self-Check Questions

基础题

1. 为什么这一讲强调先设计框架，而不是直接开始写代码？
2. 项目级框架和用户级框架分别解决什么问题？
3. .claude/commands/、skills/、agents/、hooks/ 各自的作用是什么？

进阶题

4. 为什么 constitution.md 和 CLAUDE.md 要同时存在？
5. 为什么 settings.local.json 要被 .gitignore 忽略？
6. 为什么说这个框架能把 AI 协作从“游击战”提升为“体系作战”？

思辨题

7. 你所在团队的哪些知识资产最适合迁移进这套 AI 协作框架？
8. 如果你的团队要引入 AI 协作，你会先建设 commands 还是 skills？为什么？
9. 你会如何为项目定义一份最小可用的 constitution.md？

三十一、学霸总结

Top-Student Summary

这一讲讲的是 AI 原生开发进入实战阶段前最关键的一步：先做顶层设计，先搭 AI 协作框架，再开始项目开发。

它解决的核心问题不是“Claude Code 还能干什么”，而是：

已经学会的这些能力，怎样才能被组织成一套稳定、共享、可扩展的工程系统，而不是零散的个人技巧。

Tony 用“驾驶舱”这个比喻非常准确。
因为真正的 AI 原生开发，不是单独掌握某个命令、某个 Hook、某个 Skill，而是要有一套统一的平台，把：

• 规则
• 上下文
• 自动化
• 专家能力
• 多智能体分工
• 团队知识
• 个人偏好

都安放在合适的位置，并在 Claude 启动时被自动装配起来。

这一讲最关键的架构设计，是明确区分了两层框架：

1. 项目级框架
   属于团队共享资产，定义当前项目的规则、能力和工作方式，应提交到 Git。

2. 用户级框架
   属于个人私有资产，定义跨项目的偏好与工具，不进入项目仓库。

在项目级框架中：

• .claude/commands/ 用于封装团队 SOP
• .claude/skills/ 用于沉淀团队领域知识
• .claude/agents/ 用于定义团队虚拟专家
• .claude/hooks/ 用于落地团队自动化规则
• .claude/settings.json 用于建立共享安全与行为基线
• specs/ 用于承载规范驱动开发产物
• constitution.md 用于定义项目根本原则
• CLAUDE.md 用于定义具体操作手册

用户级框架则为个人提供跨项目通用命令、技能、Agent 和偏好设置，形成自己的“私人武器库”。

因此，这一讲真正完成的升级是：

把 Claude Code 的使用，从“功能堆砌”升级为“系统架构设计”。

从这里开始，AI 不再是一个每次都临时协作的外部助手，而是一个在项目启动时就自动加载团队哲学、项目规则和最佳实践的“入职成员”。

也正因为如此，Tony 最后特别强调：
这些框架文件不只是本地配置，而是项目的 AI 协作基础设施，必须和代码、CI、Dockerfile 一样，被纳入版本控制，成为团队可传承、可演进的核心资产。

三十二、一句话记忆

One-Sentence Memory Hook

16 讲的本质，是先为项目搭建 AI 协作框架，把规则、能力、知识和自动化都放进“驾驶舱”，再让 Claude 作为真正的团队成员参与开发。