[{"data":1,"prerenderedAt":770},["ShallowReactive",2],{"blog-claude-code-team-adoption":3},{"id":4,"title":5,"body":6,"category":756,"date":757,"description":758,"extension":759,"meta":760,"navigation":253,"path":761,"seo":762,"stem":763,"tags":764,"__hash__":769},"blog\u002Fblog\u002Fclaude-code-team-adoption.md","让 Claude Code 读懂你的代码库：CLAUDE.md 分层与团队落地实践",{"type":7,"value":8,"toc":733},"minimark",[9,13,22,30,35,38,54,64,67,71,146,152,155,158,186,192,198,206,216,273,321,324,332,336,343,391,400,409,413,416,420,423,429,436,440,443,447,450,478,482,485,510,516,520,523,548,554,558,561,566,570,574,580,584,590,596,601,605,689,692,695,719,722,729],[10,11,5],"h1",{"id":12},"让-claude-code-读懂你的代码库claudemd-分层与团队落地实践",[14,15,16,17,21],"p",{},"Claude Code 最大的优势是它有工具、能改代码。但它最大的盲区也很明显：它不认识你们公司的内部框架，不知道你们团队三年沉淀下来的\"不写进文档的约定\"，更不懂那个 2000 行的 ",[18,19,20],"code",{},"legacy-pricing.ts"," 为什么碰不得。",[14,23,24,25,29],{},"所有这些隐性知识，都需要你主动编码进 CC 的\"记忆系统\"。核心载体就是 CLAUDE.md——但这不意味着把所有东西塞进一个文件。真正高效的做法是",[26,27,28],"strong",{},"分层设计","。",[31,32,34],"h2",{"id":33},"_1-不是只有一个-claudemd","1. 不是只有一个 CLAUDE.md",[14,36,37],{},"CC 的 CLAUDE.md 加载有两层逻辑：",[39,40,41,48],"ul",{},[42,43,44,47],"li",{},[26,45,46],{},"向上聚合","（启动时一次性）：从当前目录一路向上找所有 CLAUDE.md，全部加载",[42,49,50,53],{},[26,51,52],{},"向下按需","（运行时增量）：当 CC 操作某个子目录里的文件时，那子目录链路上的 CLAUDE.md 自动追加",[55,56,61],"pre",{"className":57,"code":59,"language":60},[58],"language-text","~\u002F.claude\u002FCLAUDE.md                  # 全局（你个人跨所有项目的偏好）\n\u003Crepo>\u002FCLAUDE.md                     # 项目级（启动时加载）\n\u003Crepo>\u002Fbackend\u002FCLAUDE.md             # CC 操作 backend\u002F 下文件时按需追加\n\u003Crepo>\u002Fbackend\u002Fbilling\u002FCLAUDE.md     # 操作 billing\u002F 下文件时再追加\n","text",[18,62,59],{"__ignoreMap":63},"",[14,65,66],{},"为什么根 CLAUDE.md 不够用？一条规则可能只对计费模块适用（\"金额一律 Decimal，禁止 JS number\"）——写进根会让它常驻所有会话，浪费 token。",[68,69,70],"h3",{"id":70},"推荐四层结构",[72,73,74,90],"table",{},[75,76,77],"thead",{},[78,79,80,84,87],"tr",{},[81,82,83],"th",{},"层级",[81,85,86],{},"文件",[81,88,89],{},"内容",[91,92,93,107,120,133],"tbody",{},[78,94,95,99,104],{},[96,97,98],"td",{},"全局",[96,100,101],{},[18,102,103],{},"~\u002F.claude\u002FCLAUDE.md",[96,105,106],{},"个人偏好：commit 风格、默认语言",[78,108,109,112,117],{},[96,110,111],{},"项目",[96,113,114],{},[18,115,116],{},"\u003Crepo>\u002FCLAUDE.md",[96,118,119],{},"铁律 + 目录地图 + Skills 索引 + 风格锚点",[78,121,122,125,130],{},[96,123,124],{},"子系统",[96,126,127],{},[18,128,129],{},"\u003Crepo>\u002F\u003Carea>\u002FCLAUDE.md",[96,131,132],{},"该子系统特有架构、依赖、命令",[78,134,135,138,143],{},[96,136,137],{},"模块",[96,139,140],{},[18,141,142],{},"\u003Crepo>\u002F\u003Carea>\u002F\u003Cmodule>\u002FCLAUDE.md",[96,144,145],{},"历史坑、兼容约束、\"动这里前先看 X\"",[14,147,148,151],{},[26,149,150],{},"原则：越模块化、越专有的规则越往深层子目录放；只有全局铁律才进根。"," 否则根 CLAUDE.md 迅速膨胀，无关会话也要为它付 token。",[68,153,154],{"id":154},"维护策略",[14,156,157],{},"CC 不会自动更新 CLAUDE.md——这是故意的，因为记忆文件会常驻上下文、影响后续所有会话。日常更新走四种方式：",[39,159,160,170,177,183],{},[42,161,162,165,166,169],{},[18,163,164],{},"#"," 前缀：会话里直接发 ",[18,167,168],{},"# Billing 模块金额一律用 Decimal","，最顺手",[42,171,172,173,176],{},"自然语言：\"把刚才关于 X 的决策追加到 ",[18,174,175],{},"services\u002Fbilling\u002FCLAUDE.md"," 的踩坑记录一节\"",[42,178,179,182],{},[18,180,181],{},"\u002Fmemory","：打开专用编辑视图",[42,184,185],{},"直接编辑文件：大范围重构",[14,187,188,191],{},[26,189,190],{},"什么值得回写？"," 你在不同会话里对 CC 讲过同一件事 ≥ 2 次、发现了一条希望未来所有改动都遵守的约束、修 bug 时挖出的历史坑。",[14,193,194,197],{},[26,195,196],{},"小结："," CLAUDE.md 不是一次写完的，是踩坑攒出来的。发现 CC 偏了、发现它不知道某条历史包袱 → 立刻回写到最合适的那一层。最佳时机是任务刚结束，而不是\"等以后集中整理\"。",[31,199,201,202,205],{"id":200},"_2-clauderules另一种切分维度","2. ",[18,203,204],{},".claude\u002Frules\u002F","：另一种切分维度",[14,207,208,209,211,212,215],{},"当规则更适合按\"文件类型\"而不是\"业务模块\"组织时，用 ",[18,210,204],{},"。它支持 ",[18,213,214],{},"paths"," frontmatter 做路径作用域——只有 CC 读到匹配的文件时才加载：",[55,217,221],{"className":218,"code":219,"language":220,"meta":63,"style":63},"language-markdown shiki shiki-themes github-dark","---\npaths:\n  - \"src\u002Fapi\u002F**\u002F*.ts\"\n---\n\n# API 开发规范\n- 所有入口必须先做 zod 校验\n- 错误用 AppError，不抛裸 Error\n","markdown",[18,222,223,231,237,243,248,255,261,267],{"__ignoreMap":63},[224,225,228],"span",{"class":226,"line":227},"line",1,[224,229,230],{},"---\n",[224,232,234],{"class":226,"line":233},2,[224,235,236],{},"paths:\n",[224,238,240],{"class":226,"line":239},3,[224,241,242],{},"  - \"src\u002Fapi\u002F**\u002F*.ts\"\n",[224,244,246],{"class":226,"line":245},4,[224,247,230],{},[224,249,251],{"class":226,"line":250},5,[224,252,254],{"emptyLinePlaceholder":253},true,"\n",[224,256,258],{"class":226,"line":257},6,[224,259,260],{},"# API 开发规范\n",[224,262,264],{"class":226,"line":263},7,[224,265,266],{},"- 所有入口必须先做 zod 校验\n",[224,268,270],{"class":226,"line":269},8,[224,271,272],{},"- 错误用 AppError，不抛裸 Error\n",[72,274,275,287],{},[75,276,277],{},[78,278,279,284],{},[81,280,281,282],{},"用 ",[18,283,204],{},[81,285,286],{},"用子目录 CLAUDE.md",[91,288,289,305,313],{},[78,290,291,302],{},[96,292,293,294,297,298,301],{},"规则按 glob 模式组织（",[18,295,296],{},"*.test.ts","、",[18,299,300],{},"migrations\u002F**","）",[96,303,304],{},"规则按业务模块边界组织",[78,306,307,310],{},[96,308,309],{},"同类规则跨多个目录复用",[96,311,312],{},"模块级\"动这里前先看 X\"",[78,314,315,318],{},[96,316,317],{},"细到\"只在改 React 组件时加载\"",[96,319,320],{},"模块级全套规范",[14,322,323],{},"两套机制可以并存。关键区别：rule 是常驻片段（匹配时整段注入 system prompt），Skill 是按需触发（正文只在调用时才加载）。不要把 SOP 塞进 rules——会无谓占 token。",[14,325,326,328,329,331],{},[26,327,196],{}," CLAUDE.md 管\"这个模块的规矩\"，",[18,330,204],{}," 管\"这类文件的规矩\"。两者配合才能覆盖大仓的全部场景。",[31,333,335],{"id":334},"_3-auto-memory让-cc-自己记笔记","3. Auto Memory：让 CC 自己记笔记",[14,337,338,339,342],{},"v2.1.59+ 引入的 auto memory 系统：CC 在会话中会自己判断\"这条信息以后还有用\"，写到 ",[18,340,341],{},"~\u002F.claude\u002Fprojects\u002F\u003Cproject>\u002Fmemory\u002F","。每次新会话自动加载前 200 行。",[72,344,345,357],{},[75,346,347],{},[78,348,349,351,354],{},[81,350],{},[81,352,353],{},"CLAUDE.md",[81,355,356],{},"Auto Memory",[91,358,359,370,380],{},[78,360,361,364,367],{},[96,362,363],{},"谁写",[96,365,366],{},"你",[96,368,369],{},"CC 自己",[78,371,372,374,377],{},[96,373,89],{},[96,375,376],{},"规范、铁律、架构",[96,378,379],{},"它发现的命令、纠正过的偏好",[78,381,382,385,388],{},[96,383,384],{},"角色",[96,386,387],{},"宪法",[96,389,390],{},"备忘录",[14,392,393,396,397,399],{},[26,394,395],{},"实战建议","：把 auto memory 当成低优先级补充——铁律仍然必须进 CLAUDE.md。定期 ",[18,398,181],{}," review 自动生成的记忆、删除错误条目。",[14,401,402,404,405,408],{},[26,403,196],{}," Auto Memory 节省了\"手动记 build 命令是 ",[18,406,407],{},"pnpm dev:billing","\"这种琐事，但它不是强约束。不要让 auto memory 替代 CLAUDE.md 里的关键规范。",[31,410,412],{"id":411},"_4-存量项目的-6-步-onboarding","4. 存量项目的 6 步 Onboarding",[14,414,415],{},"手里的老仓库 CC 完全不认识？按下面这套流程。",[68,417,419],{"id":418},"step-1让-cc-做考古侦察","Step 1：让 CC 做\"考古侦察\"",[14,421,422],{},"进入 Plan 模式（只读），派给 Explore subagent：",[424,425,426],"blockquote",{},[14,427,428],{},"\"你是新入职的资深工程师。生成一份项目考古报告：识别语言\u002F构建系统\u002F包管理器、目录结构及职责、内部包使用情况、历史沉淀（废弃代码\u002F风格断层）、测试策略分布、危险区域（循环依赖\u002F上帝文件\u002F热点文件）。不要修改任何代码，不确定处标 UNKNOWN。\"",[14,430,431,432,435],{},"仓库很大时，用 ",[18,433,434],{},"\u002Fbatch"," 派 5-10 个 Explore subagent 各盯一块，并行考古，主代理合并报告。子代理把脏活跑完只返回摘要，主会话上下文不爆。",[68,437,439],{"id":438},"step-2根据侦察报告分层写-claudemd","Step 2：根据侦察报告分层写 CLAUDE.md",[14,441,442],{},"至少要有：项目级铁律 + 目录地图、关键子模块特有规则、遗留代码警告（\"这别重构，只加不改\"）。",[68,444,446],{"id":445},"step-3给内部框架教教科书","Step 3：给内部框架\"教教科书\"",[14,448,449],{},"三种方式，按 ROI 从高到低：",[39,451,452,462,472],{},[42,453,454,457,458,461],{},[26,455,456],{},"方式 A（强推）","：为每个内部框架写一个 Skill。主文件 ≤ 200 行，详细 API 放 ",[18,459,460],{},"references\u002F","。description 写清楚\"遇到 import '@company\u002Frpc' 时触发\"",[42,463,464,467,468,471],{},[26,465,466],{},"方式 B","：框架文档同步到 ",[18,469,470],{},"docs\u002Fframeworks\u002F","，根 CLAUDE.md 只列索引",[42,473,474,477],{},[26,475,476],{},"方式 C","：让 CC 从代码里自学归纳——\"扫描所有使用 @company\u002Frpc 的文件，归纳典型骨架和反模式，输出为 Skill 草稿。\"然后你人工 review",[68,479,481],{"id":480},"step-4用学习示例锚定风格","Step 4：用\"学习示例\"锚定风格",[14,483,484],{},"在 CLAUDE.md 里写：",[55,486,488],{"className":218,"code":487,"language":220,"meta":63,"style":63},"## 风格锚点\n- 好样本：`src\u002Fmodules\u002Forder\u002FOrderService.ts`\n- 好样本：`src\u002Fmodules\u002Finventory\u002F` 整个模块\n- 反样本（不要学）：`src\u002Fmodules\u002Flegacy-pricing\u002F`（历史遗留，即将废弃）\n",[18,489,490,495,500,505],{"__ignoreMap":63},[224,491,492],{"class":226,"line":227},[224,493,494],{},"## 风格锚点\n",[224,496,497],{"class":226,"line":233},[224,498,499],{},"- 好样本：`src\u002Fmodules\u002Forder\u002FOrderService.ts`\n",[224,501,502],{"class":226,"line":239},[224,503,504],{},"- 好样本：`src\u002Fmodules\u002Finventory\u002F` 整个模块\n",[224,506,507],{"class":226,"line":245},[224,508,509],{},"- 反样本（不要学）：`src\u002Fmodules\u002Flegacy-pricing\u002F`（历史遗留，即将废弃）\n",[14,511,512,515],{},[26,513,514],{},"这比写 100 条风格规则都有效","——代码里已经把所有隐含规范固化了，CC 模仿能力极强。",[68,517,519],{"id":518},"step-5为方法论写硬约束","Step 5：为方法论写硬约束",[14,521,522],{},"DDD 铁律示例：",[55,524,526],{"className":218,"code":525,"language":220,"meta":63,"style":63},"## DDD 约束\n- 领域层不得 import 任何 infrastructure\u002Finterfaces 代码\n- Entity 只能通过 Repository 持久化，禁止应用层直接拼 SQL\n- 业务不变量用 ValueObject 或 Entity 方法表达，禁止在 Service 里散落校验\n",[18,527,528,533,538,543],{"__ignoreMap":63},[224,529,530],{"class":226,"line":227},[224,531,532],{},"## DDD 约束\n",[224,534,535],{"class":226,"line":233},[224,536,537],{},"- 领域层不得 import 任何 infrastructure\u002Finterfaces 代码\n",[224,539,540],{"class":226,"line":239},[224,541,542],{},"- Entity 只能通过 Repository 持久化，禁止应用层直接拼 SQL\n",[224,544,545],{"class":226,"line":245},[224,546,547],{},"- 业务不变量用 ValueObject 或 Entity 方法表达，禁止在 Service 里散落校验\n",[14,549,550,553],{},[26,551,552],{},"铁律用\"禁止\u002F必须\"句式，不要用\"建议\u002F尽量\"","——Agent 对硬约束执行力更强。",[68,555,557],{"id":556},"step-6首轮小任务校准","Step 6：首轮小任务校准",[14,559,560],{},"不要直接让 CC 上手做大需求。挑一个简单 bug 走 plan 模式，你对它的产出做严格 diff review，不符合团队风格的 → 反馈进 CLAUDE.md 或对应 Skill。再让它做第二个，迭代到产出基本符合预期。走 1-2 天，后面几个月都受益。",[14,562,563,565],{},[26,564,196],{}," 新项目落地难的不是\"配 CLAUDE.md\"，而是把你脑子里的隐性工程判断显式化。这套 6 步流程的精髓是：先考古、再分层、用示例锚定风格、小任务迭代校准——而不是一口气写完然后指望它完美。",[31,567,569],{"id":568},"_5-大仓定位代码的日更-sop","5. 大仓定位代码的日更 SOP",[68,571,573],{"id":572},"需求型我要做-x-功能涉及哪些模块","需求型：\"我要做 X 功能，涉及哪些模块？\"",[55,575,578],{"className":576,"code":577,"language":60},[58],"1. \u002Fclear\n2. @CLAUDE.md（明确涉及哪个子系统也 @ 对应 CLAUDE.md）\n3. \"进入 plan 模式。ultrathink。不要改代码。\n   调 code-explorer 去做调研，只把清单返回。\n   产出：业务流程(3-8步) \u002F 每步涉及的文件:行号 \u002F 需新增的文件 \u002F\n         需修改的文件 \u002F 风险点 \u002F 测试计划 \u002F 建议的 PR 拆分\"\n",[18,579,577],{"__ignoreMap":63},[68,581,583],{"id":582},"bug-型这个错误在哪触发的","Bug 型：\"这个错误在哪触发的？\"",[55,585,588],{"className":586,"code":587,"language":60},[58],"1. \u002Fclear + 贴完整错误信息\n2. \"ultrathink。先不要改代码。\n   a) 从 stack trace 定位最上面的业务代码帧\n   b) 提出 3 个最可能的根因假设，每个给出证据、反证、最小验证方法\n   c) 排序给出优先验证顺序\n   等我选一个再继续。\"\n",[18,589,587],{"__ignoreMap":63},[14,591,592,595],{},[26,593,594],{},"关键：两段式（先假设 → 再验证）比直接让它修 bug 效果好得多。"," 把你自己查 bug 的思维过程显式化给 CC。",[14,597,598,600],{},[26,599,196],{}," 大仓导航的核心原则是\"让 CC 在需要的时候看到需要的那部分\"。Explorer subagent 做脏活 + plan 模式防冲动 + 结构化产出便于 review——这是反复验证过的高效组合。",[31,602,604],{"id":603},"_6-一个从零让-cc-符合团队要求的-checklist","6. 一个\"从零让 CC 符合团队要求\"的 Checklist",[39,606,609,618,628,638,646,655,665,671,677,683],{"className":607},[608],"contains-task-list",[42,610,613,617],{"className":611},[612],"task-list-item",[614,615],"input",{"disabled":253,"type":616},"checkbox"," 根目录 CLAUDE.md：项目速览 + 铁律 + 目录地图 + 风格锚点 + Skills 索引",[42,619,621,623,624,627],{"className":620},[612],[614,622],{"disabled":253,"type":616}," 关键子模块 ",[18,625,626],{},"*\u002FCLAUDE.md","：模块特有规则、踩坑记录",[42,629,631,633,634,637],{"className":630},[612],[614,632],{"disabled":253,"type":616}," ",[18,635,636],{},".claude\u002Fskills\u002F"," 至少 3 个：内部框架 × N + 团队方法论",[42,639,641,633,643,645],{"className":640},[612],[614,642],{"disabled":253,"type":616},[18,644,470],{}," 同步内部框架文档（或让 CC 从代码归纳）",[42,647,649,633,651,654],{"className":648},[612],[614,650],{"disabled":253,"type":616},[18,652,653],{},".claude\u002Fsettings.json"," 配好 PostToolUse typecheck\u002Flint hook",[42,656,658,660,661,664],{"className":657},[612],[614,659],{"disabled":253,"type":616}," 配好 ",[18,662,663],{},"\u002Fpermissions","：限制危险 bash、限定工作区",[42,666,668,670],{"className":667},[612],[614,669],{"disabled":253,"type":616}," 接入 1-2 个 MCP（至少 Git 托管 + 任务系统）",[42,672,674,676],{"className":673},[612],[614,675],{"disabled":253,"type":616}," 选 2-3 个\"好样本文件\u002F模块\"写进风格锚点",[42,678,680,682],{"className":679},[612],[614,681],{"disabled":253,"type":616}," 走一次小任务校准，把发现的偏差回写到 CLAUDE.md",[42,684,686,688],{"className":685},[612],[614,687],{"disabled":253,"type":616}," 提交到 git 并让团队成员也 pull 一份",[31,690,691],{"id":691},"总结",[14,693,694],{},"让 CC 真正理解你的代码库，本质上是三件事的层层推进：",[696,697,698,704,713],"ol",{},[42,699,700,703],{},[26,701,702],{},"编码隐性知识","：把团队规范、内部框架用法、历史遗留约束从人脑搬到 CLAUDE.md 和 Skills",[42,705,706,709,710,712],{},[26,707,708],{},"精准上下文管理","：分层 CLAUDE.md + ",[18,711,204],{}," + auto memory 三层互补，确保 CC 在该看到的时候看到该看的",[42,714,715,718],{},[26,716,717],{},"迭代校准","：别指望一次写对。小任务跑起来，发现偏差就回写，两周下来准确度会有质的飞跃",[14,720,721],{},"这套体系一旦搭好，新同事 clone 仓库后开 CC 就能直接干活——架构约束、代码风格、踩坑记录全部内化在工具链里。这才是 AI 时代的团队知识管理。",[14,723,724],{},[725,726,728],"a",{"href":727},"\u002Fblog\u002F","返回博客列表",[730,731,732],"style",{},"html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}",{"title":63,"searchDepth":233,"depth":233,"links":734},[735,739,741,742,750,754,755],{"id":33,"depth":233,"text":34,"children":736},[737,738],{"id":70,"depth":239,"text":70},{"id":154,"depth":239,"text":154},{"id":200,"depth":233,"text":740},"2. .claude\u002Frules\u002F：另一种切分维度",{"id":334,"depth":233,"text":335},{"id":411,"depth":233,"text":412,"children":743},[744,745,746,747,748,749],{"id":418,"depth":239,"text":419},{"id":438,"depth":239,"text":439},{"id":445,"depth":239,"text":446},{"id":480,"depth":239,"text":481},{"id":518,"depth":239,"text":519},{"id":556,"depth":239,"text":557},{"id":568,"depth":233,"text":569,"children":751},[752,753],{"id":572,"depth":239,"text":573},{"id":582,"depth":239,"text":583},{"id":603,"depth":233,"text":604},{"id":691,"depth":233,"text":691},"AI\u002FLLM","2026-05-03","Claude Code 最大的优势是它有工具、能改代码。但它最大的盲区也很明显：它不认识你们公司的内部框架，不知道你们团队三年沉淀下来的\"不写进文档的约定\"，更不懂那个 2000 行的 legacy-pricing.ts 为什么碰不得。","md",{},"\u002Fblog\u002Fclaude-code-team-adoption",{"title":5,"description":758},"blog\u002Fclaude-code-team-adoption",[765,353,766,767,768],"Claude Code","团队协作","代码库管理","AI编程","5rt9paHjy1Wh5ZkO18-k2PMmxGChn5ShAT0nyFoy4qw",1779959652907]