Claude Code 知识管理
What it is
Claude Code 的知识管理指项目内多层上下文系统的组织方式:稳定规则(CLAUDE.md / AGENTS.md)、按需能力(Skills)、机构知识(docs/)、运行记忆(runbooks / 事故报告)与请求级验收契约各自承担不同角色。核心判断是:规则文件是 Agent contract,不是知识仓库——把所有知识塞进一份文件会让稳定纪律与临时操作混在一起,增加上下文成本并加速契约腐化。
Why it matters
- 上下文分层是性能问题:把所有知识塞进 CLAUDE.md 会浪费 token 并掩盖真正稳定的边界;HiTw93 的 Mole 实践与 pvncher 的 Skills 边界总结给出分工:架构、权限、不可触碰的边界写进 Rules;重复模块检查抽成按需 Skills;任务结果由测试、CI 和发布核验提供证据。
- 规则需要"原因注释":论文研究显示 76.8% 的规则"消失"是因为有人放弃并整文件重写;每条规则旁边写下"为什么存在"的注释,实验显示文件增速从 +211.3% 降至 +1.4%(dani_avila7 转发的 AGENTS.md 膨胀研究)。
- 知识分层是工程协作问题:Kieran Klaassen 的 Cora 文件夹把 CLAUDE.md 作为文件夹 Agent 的入口,按阅读顺序补足系统知识:架构文档 → 助手系统报告 → prompt → component creator Agent。模型只有在读取正确层级的上下文后,才会从通用模型变成代码库 specialist。
核心分层模型
| 层级 | 载体 | 内容 | 加载方式 |
|---|---|---|---|
| 稳定契约 | CLAUDE.md / AGENTS.md | 目标、权限边界、禁止行为、停止条件 | 每次会话常驻 |
| 按需能力 | Skills | 重复出现的模块检查、专门任务流程 | 相关时按 trigger 加载 |
| 机构知识 | docs/developer-docs/ | 架构决策、项目边界、命名约定 | 按阅读顺序渐进披露 |
| 运行记忆 | docs/runbooks/、docs/investigations/ | 事故历史、操作记录、诊断路径 | 任务需要时读取 |
| 请求级契约 | 单次任务 prompt | 验收标准、保护范围、停止点 | 每次非平凡请求 |
与企业知识提取瓶颈的对应
product-trends/enterprise-knowledge-extraction 指出企业 tribal knowledge 无法结构化为 AI 可用上下文。Claude Code 项目文件夹是这个问题的工程级解法:知识结构化不是"先整理再接入 AI",而是把知识按稳定性和加载成本分层,让 Agent 在正确时间读到正确约束。Aaron Levie 所说的"企业记忆碎片化"在单项目内的对应物,就是规则、技能、文档和历史读取未分层导致的上下文噪声。
Evidence across sources
- AI 简报 2026-08-13 — 规则文件膨胀研究;"为什么存在"注释使增速从 +211.3% 降至 +1.4%
- AI Briefing 2026-08-31 Evening — HiTw93 Mole 与 pvncher:Rules / Skills / CI 三层分工
- Every — The Folder Is the Agent — 项目文件夹分层:规则、机构知识、运行记忆、专门角色
- AI Briefing 2026-09-12 Evening — 规则、技能与历史读取是同一控制面;最小审计清单
- AI Briefing 2026-09-13 Afternoon — skill trigger 与 done definition 作为模型可读契约
- Tom Blomfield / Garry Tan / Aaron Levie 关于企业 tribal knowledge 的论述(经 product-trends/enterprise-knowledge-extraction 转引)
Open questions
- 规则、技能与文档的边界会随项目规模变化,加载成本应如何按项目校准?
- 文件夹层级越多,阅读成本和过期风险越高——来源、更新时间和加载边界由谁维护?
- 企业级知识基础设施(Levie 的"20+ 系统碎片化")能否复用项目文件夹的分层模型,还是面临不同的治理约束?
2026-10-15:chat-index.md 与 folder-map.md——记忆维护与结构导航
Ben's Bites 2026-10-15(14 个 Claude Code prompt 技巧)中两个技巧直接补充本页导航层:
- chat-index.md:在 CLAUDE.md 同级维护历史会话索引,记录每个项目聊过什么、结论是什么、有什么坑。新项目开始时 agent 先读它,避免重复犯已解决的错。把「记忆维护」从隐式对话历史变成显式文件。
- folder-map.md:为大仓库维护目录结构地图——每个目录做什么、为何存在、由谁负责。agent 不用每次重新探索结构,大仓库导航成本下降。
两者都是「文件即接口」的具体形态:agent 的跨会话记忆和仓库导航通过约定文件承载,与 harness-engineering/file-as-bus-pattern 互证。
Related
- claude-code/agents-md-as-contract — AGENTS.md 作为 Agent 契约
- claude-code/overview — Claude Code 核心概念
- harness-engineering/overview — Harness Engineering 框架
- product-trends/enterprise-knowledge-extraction — 企业知识提取瓶颈
- harness-engineering/agent-memory-vs-context-substrate — Agent 记忆与上下文基底
Pending Jean review
- claude-code/claude-code-knowledge-management —
ai_draft; suggested action: keep draft, then map one real project folder onto the five-layer model and measure fresh-Agent rework.
审计补证
- 工具作者以团队怎样组织和复用 Skills 为例,说明知识如何变成任务时加载的操作规则;它不证明所有团队都适合相同目录。
- Lessons from Building Claude Code - How We Use Skills