Claude 配置的四层约束架构
来源：用户设计 | 保存日期：2026-06-02 | 更新：2026-06-02（项目上下文目录 + SDD + Gateway 重启规则）
核心理念：约束从上往下穿透，一层管一层，一层约束一层。
四层架构
┌─────────────────────────────────────────────────────────┐
│ 第一层：全局 ~/CLAUDE.md │
│ "我是谁，我的原则，我期望的协作方式" │
│ 位置：用户 home 目录 │
│ 加载时机：打开任何项目都加载 │
│ 内容：人格定义、行为准则、通用协作协议 │
├─────────────────────────────────────────────────────────┤
│ 第二层：项目级 CLAUDE.md │
│ "这个项目的宪法" │
│ 位置：项目根目录 │
│ 加载时机：进入该项目文件夹时加载 │
│ 内容：目录结构规范、命名规范、文件放哪里、技术栈约束 │
├─────────────────────────────────────────────────────────┤
│ 第三层：项目规范文档 │
│ "具体怎么干" │
│ 位置：项目内各处（docs/、specs/、design/） │
│ 内容：设计文档、架构说明、API 规范、测试策略 │
├─────────────────────────────────────────────────────────┤
│ 第四层：记忆文件 │
│ "发生过什么" │
│ 位置：项目内或全局（Auto Memory、对话记录、自记笔记） │
│ 内容：历史决策、踩过的坑、当前进度、Claude 给自己的备忘 │
└─────────────────────────────────────────────────────────┘
约束穿透规则
第一层约束第二层：全局 CLAUDE.md 说「代码必须写测试」，项目的 CLAUDE.md 就不能说「这个项目不用写测试」。
第二层约束第三层：项目的 CLAUDE.md 说「目录结构是 src/ + tests/」，所有规范文档必须在这个框架下展开。
第三层约束第四层：规范文档定义了「怎么记录」，记忆文件要按规范格式来。
第四层反馈上层：记忆文件中的「踩坑记录」可以触发第二层 CLAUDE.md 的更新（新增禁令/规范）。
第二层扩展：项目上下文目录规范
来源：实际生产经验。最早为 Claude Code 制定，后来扩展到所有 AI 编码 agent。
问题
Agent 在执行过程中会在项目根目录随地创建文件——临时脚本、分析报告、中间产物。几天后项目目录变成垃圾场，无法追溯哪个文件是哪个任务产生的。
解决方案
每个项目根目录下必须有一个统一的上下文目录，所有 AI agent 的产出物强制归档到此目录下。
项目根目录/
├── .context/ # 项目上下文目录（第二层 CLAUDE.md 强制规定）
│ ├── explore/ # 探索任务 — 调研、逆向、代码走读
│ │ └── {模块名}/
│ │ ├── 2026-06-02-auth-flow-analysis.md
│ │ └── ...
│ ├── plan/ # 计划任务 — 架构设计、技术方案、实施计划
│ │ └── {模块名}/
│ │ └── 2026-06-03-refactor-plan.md
│ ├── execute/ # 执行任务 — 实现过程的记录、中间产出
│ │ └── {模块名}/
│ │ └── ...
│ ├── review/ # 审查任务 — 代码审查报告、安全检查、性能分析
│ │ └── {模块名}/
│ │ └── 2026-06-04-security-audit.md
│ ├── decisions/ # 决策记录 — 技术选型、架构决策的上下文
│ │ └── {模块名}/
│ │ └── ...
│ └── notes/ # 杂项 — 临时备忘、会话摘要
│ └── ...
│
├── .context/CLAUDE.md # 已经在这个目录里了，不用重复
├── src/ # 实际代码
└── tests/
核心规则
- Agent 产物不进项目根目录。所有分析报告、计划文档、审查记录强制写入
.context/对应子目录。 - 按任务类型分目录，再按模块分子目录。一个文件看目录就知道「谁在什么时候做了什么」。
- 文件名格式：
{日期}-{任务简述}.md。一目了然，可 grep，可排序。 - 后续任务可查看可追溯。新 agent 启动时先扫
.context/了解项目历史和已有决策，避免重复工作或冲突决策。 .context/入 git，是项目知识资产的一部分。临时产物（如notes/）可以.gitignore。
为什么这样设计
- 清爽：项目根目录只有代码和配置，没有 agent 拉的屎
- 可追溯：任何决策都能找到当时的环境和推理链
- 可复用：新 agent 可以快速了解项目上下文，不用从头探索
- 分层清晰：这是第二层约束——每个项目的 CLAUDE.md 规定
.context/的存在和结构
SDD（Subagent-Driven Development）工作流
SDD 与上述目录规范天然配合。SDD 的核心是「一个 agent 拆任务 → 多个子 agent 并行执行 → 汇总审查」。
SDD 四阶段与目录对应
┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐
│ PLAN │ → │ EXECUTE │ → │ REVIEW │ → │ MERGE │
│ 主 agent │ │ 子 agent │ │ 主 agent │ │ 主 agent │
└────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘
↓ ↓ ↓ ↓
.context/plan/ .context/exec/ .context/review/ PR / merge
| 阶段 | 产出位置 | 内容 |
|---|---|---|
| PLAN | .context/plan/{模块}/ | 任务拆解、接口定义、验收标准 |
| EXECUTE | .context/execute/{模块}/ | 每个子 agent 的产出记录 |
| REVIEW | .context/review/{模块}/ | 审查报告、问题清单、修复记录 |
| 决策 | .context/decisions/{模块}/ | 关键技术决策及理由 |
SDD 为什么配合得好
本质上，SDD 和四层约束架构都在做同一件事：加约束，定怎么做，做什么。
- 四层约束 → 约束 agent 怎么思考、怎么组织
- 项目目录规范 → 约束 agent 产出物放哪里
- SDD → 约束 agent 怎么拆任务、怎么协作
层层叠加，agent 的自由度越来越小，产出越来越可控、可预测。
与 Hermes 上下文系统的对应
| Claude 层 | Hermes 等价物 | 位置 | 说明 |
|---|---|---|---|
| 第一层：全局 CLAUDE.md | SOUL.md | ~/.hermes/SOUL.md | 最高指令，你是谁 |
| 第二层：项目级 CLAUDE.md | AGENTS.md / CLAUDE.md / .hermes.md | 项目根目录 | 自动发现，优先级：.hermes.md > AGENTS.md > CLAUDE.md |
| 第三层：规范文档 | Skills + 项目文档 | ~/.hermes/skills/ + 项目内 | 流程知识 + 设计文档 |
| 第四层：记忆文件 | Memory + state.db + sessions | ~/.hermes/ | 持久偏好 + 对话历史 |
Hermes 的上下文加载优先级（源码 agent/prompt_builder.py）：
- SOUL.md（第一层，永远加载）
.hermes.md或AGENTS.md或CLAUDE.md（第二层，只加载一个，按优先级）.cursorrules（第三层，cwd 内）- Skills 索引 + Memory 注入（第三/四层混合）
Hermes 系统提示词的三层拼装机制
前面说的是 Claude 的约束架构。在 Hermes 内部，发给大模型的最终 system prompt 是另一套三层拼装，底层原理不同但设计思想相通：
┌────────────────────────────────────────┐
│ STABLE（稳定层） │
│ SOUL.md + 工具指引 + Skills列表 + │
│ 环境提示 + 平台提示 + 模型指引 │
│ 生命周期：进程级，极少变化 │
├────────────────────────────────────────┤
│ CONTEXT（上下文层） │
│ system_message + AGENTS.md/.cursorrules │
│ 生命周期：会话级，/reset 后重建 │
├────────────────────────────────────────┤
│ VOLATILE（易变层） │
│ MEMORY + USER PROFILE + 时间戳 │
│ 生命周期：每次重建都刷新 │
├────────────────────────────────────────┤
│ ephemeral_system_prompt（人格附加层） │
│ /personality 设置的人设 │
│ 不进入缓存，每次 API 调用时拼接 │
└────────────────────────────────────────┘
前三层一旦拼好就缓存不动——这是为了最大化 LLM 提供商的前缀缓存命中率（省 Token + 低延迟）。人格层单独追加，所以切人设不影响缓存。
Gateway 重启规则：什么操作必须重启，什么不用
这是实操中最容易搞混的地方。记住一个原则：取决于改的东西在不在 agent cache 的「签名」里。
什么是「签名」
Gateway 会为每个会话缓存一个 AIAgent 实例（因为创建 agent 要读 SOUL.md、加载 skills、拼 system prompt，很贵）。为了判断「缓存的 agent 还能不能用」，Gateway 算一个哈希指纹（签名），包括：
- model、provider、api_key、base_url
- enabled_toolsets（启用了哪些工具集）
- ephemeral_prompt（人格 overlay）
- config.yaml 中的 model.context_length、compression.* 等
签名变了 → 丢旧 agent → 建新 agent → 自动生效，不用重启。
签名没覆盖的东西变了 → 旧 agent 继续用旧值 → 需要重启或 /reset。
操作对照表
| 操作 | 是否需要重启 Gateway | 原因 |
|---|---|---|
/personality coach | ❌ 不需要 | ephemeral_prompt 在签名里，切了自动建新 agent |
/model 切换模型 | ❌ 不需要 | model/provider 在签名里 |
修改 config.yaml 中 model/compression 相关 | ❌ 不需要 | cache_keys 机制纳入签名 |
| 开关 toolsets | ❌ 不需要 | enabled_toolsets 在签名里 |
| 修改 SOUL.md | /reset 即可 | SOUL.md 不在签名里，/reset 能触发 agent 重建 |
| 安装/删除 Skills | /reset 即可 | Skills 列表不在签名里，/reset 能触发 agent 重建 |
| 修改 platform hints 或环境变量 | ✅ 需要重启 | 不在签名里，且是 STABLE 层内容 |
修改 .env API keys | ✅ 需要重启 | 环境变量只在启动时加载一次 |
/reset 是干什么的
/reset = 清除当前会话的对话历史 + 丢弃缓存的 agent → 下次消息时创建全新 agent → 重新读 SOUL.md、重新扫 skills、重新拼 system prompt。
相当于「不重启 Gateway，但让当前会话重来一遍」。 改了 SOUL.md 或装了新 skill 后，在当前飞书/Discord 等会话里发 /reset 就行，不用重启整个 Gateway。
人格切换为什么不需要重启
人格 overlay 通过 ephemeral_system_prompt 注入，不进入三层缓存。/personality coach 做的事：
self._ephemeral_system_prompt = "coach 人设的 prompt 文本"
下次消息时，Gateway 发现 ephemeral_prompt 变了 → 签名不匹配 → 创建新 agent（重建三层 system prompt）→ 新 agent 的 API 调用时，ephemeral_prompt 追加到 system prompt 末尾。
整个过程对用户透明，一条 /personality 命令就搞定。
设计要点
层次之间互不覆盖，只做叠加：
- 全局说「你是谁」，项目说「在这个项目里你额外注意什么」
- 项目规范文档说「具体怎么做」，记忆文件说「上次怎么做的」
- 冲突时上层优先（全局 > 项目 > 规范 > 记忆）
每一层只定义该层该管的事：
- 第一层不写项目特定内容（比如「React 项目要用函数组件」应该放第二层）
- 第二层不写实现细节（比如「useEffect 的清理函数」应该放第三层）
- 第三层不写个人偏好（比如「回复用中文」应该放第一层）
更新机制：
- 第一层：手动维护，很少变
- 第二层：项目初始化时创建，随项目演进更新
- 第三层：随开发推进持续新增
- 第四层：自动生成（memory + session 自动记录）
参考案例：数字生命卡兹克的全局 CLAUDE.md
来源：数字生命卡兹克（公众号），虚实传媒创始人，用户体验设计师出身。
这是一份真实的第一层（全局 CLAUDE.md）范例，展示了完整的「我是谁 + 我的原则 + 我期望的协作方式」。
关于我
数字生命卡兹克，虚实传媒创始人。用户体验设计师出身，不是程序员。用 Claude Code 做两件事：开发产品和知识管理。
工作哲学：把任何重复 3 遍的事 AI 化或自动化。
技术决策跟我说「为什么」和「对用户的影响」，不要只讲实现。
第一性原理
所有决策从问题本质出发，不因「惯例如此」照搬。回到问题本身：要解决什么？最直接的路径是什么？从零设计会怎么做？
不要谄媚。 不要夸我的想法好、不要说「这是个很好的问题」、不要开头加「当然可以」。给我真实判断——方案有问题直接指出来。发现更好的做法直接说，不用等我问。
约束先行
无论开发项目还是知识管理项目，第一步永远是建规则：新项目先写 CLAUDE.md，新目录先定结构约定（什么放哪、怎么命名、何时清理）。
没有规范的工作空间不动手。已有规范的项目，严格遵守其 CLAUDE.md 中的约定。
需要调整规范时先改文档、再改实践，不要反过来。
交互设计原则
用户体验是所有产品的最高准则，优先级高于技术偏好、代码整洁度、架构优雅度。后端可以很复杂，但用户触碰到的每一层必须丝滑。
这不只是 GUI——CLI、对话式交互、Skill、系统反馈，都是交互体验。所有界面都适用以下原则：
- 为目标设计，不为功能设计：先问「用户要完成什么」，再决定怎么实现。不要因为技术上能做就加功能
- 不要让用户思考：交互应该不言自明。需要说明书才能用，设计就是失败的
- 系统承担复杂性：能自动化的不手动，能推断的不让用户填，能一步完成的不拆成三步
- 渐进式展示：先给核心，细节按需展开。不要一次性把所有选项甩给用户
- 反馈引导行动：不要只报告问题（“连接失败”），要引导下一步（“正在重试，预计 5 秒后恢复”）
工作方式
- 默认中文，代码、命令、变量名用英文
- 结论先行，再给理由，不要先铺垫背景
- 遇到模糊需求，先给最合理的方案，再问要不要调整
- 不要问「你确定要这样吗」——除非有真实风险
开发习惯
- 改完主动跑验证（test / lint / build），不要只改不验
- 不要为了让代码跑起来而注释掉报错，找根本原因
- 密钥、token、密码不进代码
Git 与部署
- commit message 用英文，简洁描述变更意图
- git push 仅用于跨设备同步，不要自动执行，等我说
- 部署走项目自己的命令（查项目 CLAUDE.md），不依赖 git push
实践建议
对于 Hermes 用户：
- SOUL.md（第一层）：放不随项目变化的恒常设定——语言、风格、通用原则
- 项目 .hermes.md（第二层）：每个项目根目录放一个，定义该项目的目录结构（含
.context/规范）、命名规范、技术约束 - 项目
.context/目录：所有 agent 产出物按 explore/plan/execute/review/decisions 归档，模块子目录管理 - Skills（第三层）：可复用的操作流程，跨项目共享
- Memory（第四层）：让 Hermes 自动管理，不要手动写