CLAUDE.md 项目指令
Claude Code 启动时自动读取的项目指令文件——它不是普通配置，而是给每次新会话植入记忆的”行为宪法”，让 LLM 每次开工都知道”你是谁、系统长什么样、什么能做什么不能做”。
简介
CLAUDE.md 是 Claude Code 在启动时自动读取的项目级指令文件。它解决的核心问题是：每次在 Claude Code 里启动新会话，LLM 对你的项目一无所知——你得重新告诉它目录结构、工具怎么用、哪些事不能做。如果这些信息不在一个固定的地方等着它，每个新会话就像一次失忆重来。CLAUDE.md 把这些信息固定下来，让 LLM 每次开始工作时都是”接着上次继续”，而不是”从零开始”。
@Sean 在《3 个脚本、4 个 Skill、3 层防线》中给出一个精准比喻：如果整个知识库是一个”知识加工工厂”，CLAUDE.md 就是”创造这个工厂的加工厂的厂规”——有了它，LLM 每次工作时都知道自己是谁、当前系统长什么样、哪些事可以做、哪些不能做。它的本质”不仅是给 AI 写一份说明书，而且是给每次新会话植入一份记忆”。
CLAUDE.md 是 上下文工程 在项目级的核心实践形态，与 Skill、Memory、状态文件 一起构成 LLM 协作系统的”持久记忆层”。它和 AGENTS.md 规范文件 属于同一类机制：用一份固定的规范文件约束 AI 行为，把”每次口头叮嘱”变成”一次写定、永久生效”。
关键信息
- 类型：项目指令文件 / 行为规范 / 上下文工程实践
- 载体：Markdown 文件，放在项目根目录，Claude Code 启动时自动读取
- 核心作用：给每次新会话植入统一的项目记忆和行为约束
- 上游关系：上下文工程 的项目级落地
- 相关概念：Claude Code、Skill、Claude Memory、状态文件、AGENTS.md 规范文件、知识库构建工程
核心特性
1. 一份 CLAUDE.md 通常包含的几块内容
@Sean 的知识库 CLAUDE.md 大致分五块，可作为通用模板参考：
| 板块 | 作用 | 典型内容 |
|---|---|---|
| 项目定位 | 决定 LLM 如何理解自己的角色 | ”这不是笔记收集系统，而是由 LLM 协同维护的个人领域 wiki 系统” |
| 系统结构 | 让 LLM 知道文件如何在各层流转 | 完整目录树 + 每层职责 + 文件流转路径（Inbox→Processed→Review→Archives） |
| 当前系统能力 | 让 LLM 知道有哪些工具、何时触发 | 3 个脚本 + 4 个 Skill 各干什么、核心流程和约束（摘要版，详细在各 SKILL.md） |
| 规范和约束 | 直接影响后续校验和治理 | frontmatter 最小字段集、知识卡片五种 type、状态流转规则、YAML 引号规则、禁区 |
| 当前知识库 Dashboard | 以最低成本让 LLM 了解基线 | 统计数据 + 简短摘要，描述知识库现状 |
其中”项目定位”这一句最关键——它”决定 LLM 在后续所有操作中怎么理解自己的角色”。
2. 禁区（红线）要写得非常具体
规范和约束里最重要的是明确的禁区。@Sean 举例：“不能修改 Archives 下的原始文档，不能跳过校验直接产卡。“这类硬约束直接影响后续的校验和治理脚本，必须写得非常具体，不能只写”请谨慎操作”。这与 准入准出条件 是同一类思路：拦住 AI 不做什么，比告诉它做什么更难也更重要。
3. CLAUDE.md 本身也在演进
CLAUDE.md 不是写完就放着的文档，而是”系统的实时快照”。@Sean 的演进轨迹很典型：
- 第一版：只有二十几行，写了目录结构和基本规则
- 搭建高峰期：扩展到大几百行，涵盖项目定位、当前进展、下一步规划、Skills 摘要、技术栈等完整信息
- 系统学习 Claude Code memory 能力后：精简回 100 多行——很多规则迁移到
.claude/rules下，知识库项目搭建的进展和计划迁移到 ROADMAP.md，用@的方式在必要位置引入
每次系统出现新变化（新增 Skill、完成一轮治理升级、达成阶段目标），作者都同步更新 CLAUDE.md。
4. 维护方式：先写能跑的，改完用下一次操作验证
CLAUDE.md 的维护方式和 Skill 一样——先写一版能跑的，用着用着发现哪里不对就补一条规则。关键纪律是”不要一次改很多条，改完用下一次操作来验证”。这与知识库整体的”先手动跑通、痛点出现时再加能力”方法论一致（见 知识库构建工程）。
不同素材中的观点
-
2026-07-11-woshipm-knowledge-base-engineering-practice：@Sean 把 CLAUDE.md 定位为整套知识库系统的”地基”和”行为宪法”。四个 Skill 看起来各自独立，但它们能被 Claude Code 按一套统一规范构建出来并正确执行，靠的是共同底座 CLAUDE.md。文章强调三点：(1) 它的本质是”给每次新会话植入记忆”，没有它 AI 每次从零开始；(2) 项目定位那句话决定 LLM 如何理解自己的角色；(3) 它本身要随系统演进，用 memory /
.claude/rules/ ROADMAP.md +@引入的方式做减法，避免无限膨胀。CLAUDE.md 解决”AI 知道该怎么做”的问题，但”知道该怎么做”和”真的做对了”是两件事——后者需要三层防线（见 Harness闭环工程）来守执行质量。 -
2026-05-28-woshipm-llm-wiki-qmd-architecture：秋孝隱把 CLAUDE.md 定义为整套 LLM Wiki 系统的”行为规范手册”而非配置文件，给出六维度内容：角色定义（两条红线：不改 raw 不改 log）、知识库定位、新会话启动流程、Ingest 流程、Query 流程、页面格式模板。维护策略同样是”先写一版能跑的，每次改一条，用下一篇文章测试”。两篇素材在 CLAUDE.md 的定位（行为规范/宪法）、内容结构（角色+结构+流程+约束）、维护方式（渐进式、一次一条）上高度一致，形成互证。
实用信息
快速上手：写第一版 CLAUDE.md
- 先写项目定位：一句话说清”这个项目是什么、LLM 在其中扮演什么角色”（这句最重要）
- 贴一棵目录树：让 LLM 知道文件放哪、各目录职责、文件如何流转
- 列出核心流程：常用任务（如 ingest / query）的关键步骤，详细规则放各自的 Skill/规则文件
- 写死禁区：用绝对化措辞列出不能做的事（“不能修改 X""不能跳过 Y”）
- 放一个 Dashboard 快照：几个统计数字 + 一句现状摘要，让 LLM 低成本了解基线
维护与瘦身技巧
- 一次只改一条：改完用下一次真实操作验证是否生效，不要一次堆很多规则
- 随系统演进同步更新：新增能力、完成治理、达成目标时同步刷新
- 膨胀后做减法：把细分规则迁移到
.claude/rules、把进展计划迁移到 ROADMAP.md，主文件用@引入，控制在百行量级 - 配合 Memory 用：小教训先进 Claude Memory，稳定后再整合进 CLAUDE.md 或规则文件
注意事项
- CLAUDE.md 只解决”AI 知道该怎么做”，不保证”真的做对了”——执行质量要靠校验脚本、治理 Skill 等 Harness 机制守（见 Harness闭环工程）
- 禁区和字段规范要具体到能被程序校验，否则后续 lint/治理无法落地
- 不要把所有细节塞进一个文件，按职责拆分到规则文件，主文件保持可读