[{"data":1,"prerenderedAt":529},["ShallowReactive",2],{"header-counts":3,"playbook-onboarding\u002Flegacy-codebase-onboarding":6,"footer-counts":526},{"tools":4,"reviews":5},65,7,{"id":7,"title":8,"body":9,"category":507,"cover":508,"description":509,"extension":510,"meta":511,"navigation":512,"path":513,"published":514,"relatedTools":515,"seo":519,"stem":520,"tags":521,"updated":524,"__hash__":525},"playbook\u002Fplaybook\u002Fonboarding\u002Flegacy-codebase-onboarding.md","用 AI 接手老代码：陌生项目 onboarding 工作流",{"type":10,"value":11,"toc":494},"minimark",[12,16,32,39,43,54,61,64,68,153,156,162,172,178,180,184,187,193,210,212,216,222,232,243,245,249,256,262,272,274,278,284,290,292,296,299,305,311,313,316,408,415,417,420,456,459,483,490],[13,14,15],"h2",{"id":15},"适用场景",[17,18,19,23,26,29],"ul",{},[20,21,22],"li",{},"新人入职，被丢给一个 5 年老项目",[20,24,25],{},"接手前同事跑路留下的代码",[20,27,28],{},"评估一个开源项目能否用作技术选型",[20,30,31],{},"给客户做代码 audit \u002F 接手报价",[33,34,35],"p",{},[36,37,38],"strong",{},"用人脑读两周做的事，AI 协助下 2-4 小时完成 80%。",[13,40,42],{"id":41},"总览六步法","总览：六步法",[44,45,51],"pre",{"className":46,"code":48,"language":49,"meta":50},[47],"language-text","1. clone & 准备 → 2. 项目体检 → 3. 架构图 → 4. 核心路径 →\n5. 风险与债务 → 6. 关键问题清单\n","text","",[52,53,48],"code",{"__ignoreMap":50},[33,55,56,57,60],{},"每一步都有",[36,58,59],{},"具体 Prompt + 验收标准","。",[62,63],"hr",{},[13,65,67],{"id":66},"step-1-clone-与环境准备10-分钟","Step 1 — clone 与环境准备（10 分钟）",[44,69,73],{"className":70,"code":71,"language":72,"meta":50,"style":50},"language-bash shiki shiki-themes github-light github-dark","git clone \u003Crepo>\ncd \u003Crepo>\n# 关键：先让 AI 看 git 历史活跃度\ngit log --since='1 year ago' --pretty=format:'%h %s' | wc -l\n","bash",[52,74,75,102,117,124],{"__ignoreMap":50},[76,77,80,84,88,92,95,99],"span",{"class":78,"line":79},"line",1,[76,81,83],{"class":82},"sScJk","git",[76,85,87],{"class":86},"sZZnC"," clone",[76,89,91],{"class":90},"szBVR"," \u003C",[76,93,94],{"class":86},"rep",[76,96,98],{"class":97},"sVt8B","o",[76,100,101],{"class":90},">\n",[76,103,105,109,111,113,115],{"class":78,"line":104},2,[76,106,108],{"class":107},"sj4cs","cd",[76,110,91],{"class":90},[76,112,94],{"class":86},[76,114,98],{"class":97},[76,116,101],{"class":90},[76,118,120],{"class":78,"line":119},3,[76,121,123],{"class":122},"sJ8bj","# 关键：先让 AI 看 git 历史活跃度\n",[76,125,127,129,132,135,138,141,144,147,150],{"class":78,"line":126},4,[76,128,83],{"class":82},[76,130,131],{"class":86}," log",[76,133,134],{"class":107}," --since=",[76,136,137],{"class":86},"'1 year ago'",[76,139,140],{"class":107}," --pretty=format:",[76,142,143],{"class":86},"'%h %s'",[76,145,146],{"class":90}," |",[76,148,149],{"class":82}," wc",[76,151,152],{"class":107}," -l\n",[33,154,155],{},"打开 Claude Code 或 Cursor，进入项目目录。",[33,157,158,161],{},[36,159,160],{},"第一条 Prompt","：",[163,164,165],"blockquote",{},[33,166,167,168,171],{},"\"请扫描当前目录，告诉我：(1) 这是什么类型的项目；(2) 主要技术栈；(3) 入口文件在哪；(4) 有没有 README \u002F docs。",[36,169,170],{},"先不要读源码","，只看 package.json \u002F pyproject.toml \u002F Cargo.toml \u002F go.mod 这类元文件。\"",[33,173,174,177],{},[36,175,176],{},"为什么","：先让 AI 建立宏观认知，避免它一上来就被某个文件带偏。",[62,179],{},[13,181,183],{"id":182},"step-2-项目体检20-分钟","Step 2 — 项目体检（20 分钟）",[33,185,186],{},"让 AI 出一份\"健康报告\"：",[44,188,191],{"className":189,"code":190,"language":49,"meta":50},[47],"请生成一份项目体检报告，包含：\n\n1. 代码量：按语言\u002F目录分布\n2. 测试覆盖：有没有测试，跑得起来吗，覆盖率多少\n3. 依赖健康：有几个依赖、最旧的几个分别多久没更新\n4. 文档完整度：README \u002F CHANGELOG \u002F CONTRIBUTING \u002F docs\u002F\n5. CI 状态：有 CI 吗，最近一次跑成功了吗\n6. 死代码迹象：明显未使用的文件 \u002F 函数\n\n不要猜测，只报告确凿能看到的事实。每条结论给出依据。\n",[52,192,190],{"__ignoreMap":50},[33,194,195,198,199,202,203,202,206,209],{},[36,196,197],{},"Claude Code 做这事最强","——它会自己跑 ",[52,200,201],{},"find","、",[52,204,205],{},"git log",[52,207,208],{},"npm outdated"," 这类命令，给出真凭实据。",[62,211],{},[13,213,215],{"id":214},"step-3-架构图30-分钟","Step 3 — 架构图（30 分钟）",[44,217,220],{"className":218,"code":219,"language":49,"meta":50},[47],"基于刚才的体检，画一张项目架构图（Mermaid 格式）。\n要求：\n- 顶层模块用方框\n- 数据流向用箭头\n- 外部依赖（DB \u002F 第三方 API \u002F 队列）单独标出\n- **如果某个边界你不确定，标 \"?\" 而不是猜**\n\n画完后，用 5-10 句话解释这个架构的核心思路。\n",[52,221,219],{"__ignoreMap":50},[33,223,224,227,228,231],{},[36,225,226],{},"关键技巧","：明确告诉 AI ",[36,229,230],{},"\"不确定就标 ?\"","，否则它会编。",[33,233,234,235,242],{},"把生成的 Mermaid 复制到 ",[236,237,241],"a",{"href":238,"rel":239},"https:\u002F\u002Fmermaid.live",[240],"nofollow","mermaid.live"," 验证可视化效果。",[62,244],{},[13,246,248],{"id":247},"step-4-找到核心路径30-分钟","Step 4 — 找到\"核心路径\"（30 分钟）",[33,250,251,252,255],{},"这是 onboarding 最关键的一步。每个项目都有 1-3 条",[36,253,254],{},"核心业务路径","——用户最常用的功能链路。把它走通，整个项目就懂一半了。",[44,257,260],{"className":258,"code":259,"language":49,"meta":50},[47],"请找出本项目的 3 条核心业务路径（按重要性排序）：\n\n每条路径需要回答：\n1. 用户从哪触发（URL \u002F API endpoint \u002F CLI 命令）\n2. 经过哪些关键文件 \u002F 函数\n3. 数据如何流动（DB 读什么、写什么）\n4. 在哪里返回结果\n\n用编号列表给出，每个文件名 + 行号都要确凿。\n",[52,261,259],{"__ignoreMap":50},[33,263,264,267,268,271],{},[36,265,266],{},"验收标准","：你能照着这份路径，",[36,269,270],{},"自己手动 trace 一遍而不卡壳","。如果哪一步看不懂，回去问 AI 那一段具体是什么。",[62,273],{},[13,275,277],{"id":276},"step-5-风险-技术债清单30-分钟","Step 5 — 风险 + 技术债清单（30 分钟）",[44,279,282],{"className":280,"code":281,"language":49,"meta":50},[47],"请审视代码库，列出：\n\nA. 高风险代码（运行时容易出问题）\n   - 没有错误处理的 IO \u002F 网络调用\n   - 明显的 race condition \u002F 并发问题\n   - 写死的 secret \u002F API key\n   - SQL 注入 \u002F XSS 风险\n\nB. 技术债（影响开发效率）\n   - 重复的代码 (DRY 违反)\n   - 函数过长（>200 行）\n   - 圈复杂度过高的函数\n   - 循环依赖\n\nC. 维护性差的部分\n   - 完全没注释的关键算法\n   - \"magic number\"\n   - 命名混乱的模块\n\n每条给出文件路径 + 行号，并用 1 句话解释为什么是问题。\n",[52,283,281],{"__ignoreMap":50},[33,285,286,289],{},[36,287,288],{},"这一步的输出可以直接交给客户\u002F老板","——如果你是接外包、做 audit，这就是付费报告的核心内容。",[62,291],{},[13,293,295],{"id":294},"step-6-关键问题清单20-分钟","Step 6 — 关键问题清单（20 分钟）",[33,297,298],{},"最后一步，让 AI 列出\"作为新人接手，你最该问原作者的 10 个问题\"：",[44,300,303],{"className":301,"code":302,"language":49,"meta":50},[47],"假设你即将接手这个项目，原作者今天最后一天上班，\n你只能问他 10 个问题。请列出这 10 个问题，按重要性排序。\n\n每个问题要：\n- 具体（不能是\"这个项目怎么部署\"这种宽泛问题）\n- 可被一句话回答\n- 解决之后你能独立运行\u002F修改这个项目\n",[52,304,302],{"__ignoreMap":50},[33,306,307,310],{},[36,308,309],{},"这份清单极其有价值","——它把\"未知的未知\"转化成\"已知的未知\"。你可以拿着它去问前同事 \u002F 客户 \u002F 文档 \u002F 社区。",[62,312],{},[13,314,315],{"id":315},"总耗时与产出",[317,318,319,335],"table",{},[320,321,322],"thead",{},[323,324,325,329,332],"tr",{},[326,327,328],"th",{},"阶段",[326,330,331],{},"耗时",[326,333,334],{},"产出物",[336,337,338,350,360,370,380,391],"tbody",{},[323,339,340,344,347],{},[341,342,343],"td",{},"1-2",[341,345,346],{},"30 min",[341,348,349],{},"项目体检报告",[323,351,352,355,357],{},[341,353,354],{},"3",[341,356,346],{},[341,358,359],{},"Mermaid 架构图",[323,361,362,365,367],{},[341,363,364],{},"4",[341,366,346],{},[341,368,369],{},"核心业务路径文档",[323,371,372,375,377],{},[341,373,374],{},"5",[341,376,346],{},[341,378,379],{},"风险 + 技术债清单",[323,381,382,385,388],{},[341,383,384],{},"6",[341,386,387],{},"20 min",[341,389,390],{},"关键问题清单",[323,392,393,398,403],{},[341,394,395],{},[36,396,397],{},"合计",[341,399,400],{},[36,401,402],{},"~2.5 小时",[341,404,405],{},[36,406,407],{},"5 份可交付文档",[33,409,410,411,414],{},"把这 5 份文档存进项目 ",[52,412,413],{},"docs\u002Fonboarding\u002F","，下一个新人来直接读，再省 2 小时。",[62,416],{},[13,418,419],{"id":419},"工具选择",[17,421,422,431,440,450],{},[20,423,424,427,428,60],{},[36,425,426],{},"Claude Code","：最适合这种\"广撒网\"任务，自己跑命令、读文件。",[36,429,430],{},"首选",[20,432,433,439],{},[36,434,435,436],{},"Cursor + ",[52,437,438],{},"@codebase","：体验也很好，胜在便宜。中型项目（\u003C 5 万行）够用。",[20,441,442,445,446,449],{},[36,443,444],{},"Aider","：可以，但要手动 ",[52,447,448],{},"add"," 文件，节奏更慢。",[20,451,452,455],{},[36,453,454],{},"Trae","：国内项目首选，中文 prompt 体验最佳。",[13,457,458],{"id":458},"踩坑",[17,460,461,471,477],{},[20,462,463,466,467,470],{},[36,464,465],{},"不要让 AI 一次读完整个项目","——它会丢上下文。",[36,468,469],{},"分模块"," + 每模块独立提问。",[20,472,473,476],{},[36,474,475],{},"关键结论要让它给出文件:行号"," 作为依据，否则容易编。",[20,478,479,482],{},[36,480,481],{},"不要过度依赖 AI 的\"我觉得\"","——遇到不确定的地方，强制让它标记不确定，然后人工 verify。",[33,484,485,486,60],{},"下一篇：",[236,487,489],{"href":488},"\u002Fplaybook\u002Frefactor\u002Flarge-refactor-with-ai-agent","大型重构工作流",[491,492,493],"style",{},"html pre.shiki code .sScJk, html code.shiki .sScJk{--shiki-default:#6F42C1;--shiki-dark:#B392F0}html pre.shiki code .sZZnC, html code.shiki .sZZnC{--shiki-default:#032F62;--shiki-dark:#9ECBFF}html pre.shiki code .szBVR, html code.shiki .szBVR{--shiki-default:#D73A49;--shiki-dark:#F97583}html pre.shiki code .sVt8B, html code.shiki .sVt8B{--shiki-default:#24292E;--shiki-dark:#E1E4E8}html pre.shiki code .sj4cs, html code.shiki .sj4cs{--shiki-default:#005CC5;--shiki-dark:#79B8FF}html pre.shiki code .sJ8bj, html code.shiki .sJ8bj{--shiki-default:#6A737D;--shiki-dark:#6A737D}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);}html .dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html.dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}",{"title":50,"searchDepth":119,"depth":119,"links":495},[496,497,498,499,500,501,502,503,504,505,506],{"id":15,"depth":104,"text":15},{"id":41,"depth":104,"text":42},{"id":66,"depth":104,"text":67},{"id":182,"depth":104,"text":183},{"id":214,"depth":104,"text":215},{"id":247,"depth":104,"text":248},{"id":276,"depth":104,"text":277},{"id":294,"depth":104,"text":295},{"id":315,"depth":104,"text":315},{"id":419,"depth":104,"text":419},{"id":458,"depth":104,"text":458},"onboarding","\u002Fog\u002Fplaybook\u002Flegacy-onboarding.png","新人面对几十万行老代码不知从何下手？用 Claude Code \u002F Cursor 在 2 小时内画出项目架构、找到核心入口、定位关键风险点的标准化工作流。","md",{},true,"\u002Fplaybook\u002Fonboarding\u002Flegacy-codebase-onboarding","2026-04-25",[516,517,518],"coding\u002Fcli\u002Fclaude-code","coding\u002Fide\u002Fcursor","coding\u002Fcli\u002Faider",{"title":8,"description":509},"playbook\u002Fonboarding\u002Flegacy-codebase-onboarding",[507,522,523,426],"代码理解","架构图","2026-06-08","0F1OVuaSvo8nT4EWBpyuDs7C5ypSOig0svKHVsTriyM",{"tools":4,"reviews":5,"playbooks":527,"news":528},10,8,1782316489336]