我把它拆成两层：前半部分用 9 张中文工坊图先讲一遍我的理解；后半部分按照原文结构做一版中文译读/转述，并把原文配图放回对应位置。后半部分不是逐字全文翻译，主要是为了保留原文阅读节奏，同时避免变成简单转载。

先用 9 张图讲一遍

1. 任务先进入专用脚手架，再分派给子任务

任务先进入专用脚手架，再分派给子任务。

dynamic workflow 的关键不是“多叫几个 agent”，而是先为当前任务搭一个临时 harness。任务进入脚手架后，会被拆成子任务、校验和汇总等步骤。这样 Claude Code 不再只是在一个聊天上下文里连续思考，而是在一个可编排的小系统里推进工作。

2. 单窗口长跑容易半途停、自我偏和目标漂

单窗口长跑容易半途停、自我偏和目标漂。

复杂任务放在一个上下文窗口里跑久了，会出现三种典型问题：做一半就宣布完成，过度相信自己刚产出的结论，以及在多轮压缩后偏离最初目标。workflow 的价值，是把任务拆到独立上下文里，并让不同 agent 互相检查，减少这些长任务里的自然损耗。

3. 脚本决定派谁、用什么模型、在哪里跑

脚本决定派谁、用什么模型、在哪里跑。

dynamic workflow 会执行一个 JavaScript 文件。这个脚本可以派发子 agent、选择模型、开独立 worktree，也能记录状态以便中断后恢复。它不是替代模型思考，而是把“谁来做、怎么验证、何时继续”这些调度动作写清楚，让复杂任务更像可重跑的流程。

4. 分类、并行、互查、锦标赛和循环可组合

分类、并行、互查、锦标赛和循环可组合。

文章列了几种常见 pattern：先分类再路由、并行拆解后合成、对抗式验证、生成后筛选、锦标赛选择，以及循环直到达成停止条件。真正有用的 workflow 往往不是单一套路，而是把这些小结构按任务需要拼起来。

5. 重构、研究、核验、分诊、记忆和评测都适合

重构、研究、核验、分诊、记忆和评测都适合。

workflow 特别适合那些工作量大、可以并行、需要复查、判断带主观性的任务。比如大规模重构、深度研究、事实核验、支持工单分诊、从会话中提炼项目规则、做轻量 eval。它的共同点是：单个上下文容易忙乱，但拆开后可以更稳。

6. 要看是否值得消耗更多 token 和调度成本

要看是否值得消耗更多 token 和调度成本。

dynamic workflows 会消耗更多 token 和时间，所以不该默认用于所有任务。普通小修、小范围编码、线性明确的问题，用普通模式更直接。判断是否使用 workflow，可以问三个问题：是否需要并行上下文？是否需要独立验证？是否有明确停止条件？答案越多是“是”，越值得开 workflow。

7. 静态 workflow 像固定模板，动态 workflow 像现场搭台

静态 workflow 像固定模板，动态 workflow 像现场搭台。

静态 workflow 的好处是可复用、稳定，但为了覆盖很多情况，往往会偏通用。dynamic workflow 则让 Claude 根据当前任务现场生成 harness：任务是什么形状，脚手架就怎么接线。这个区别解释了为什么文章强调“custom-built for the task at hand”。

8. 多个假设分头验证，再把证据合回修复

多个假设分头验证，再把证据合回修复。

偶发测试失败很适合 workflow，因为单一路径容易过早相信某个猜测。更稳的做法是让不同 agent 提出独立假设，在不同分支里复现和验证，再由校验步骤审查证据。最后只有能解释失败、能复现、能通过验证的假设才进入修复。

9. 不可信输入进隔离区，复核后才执行动作

不可信输入进隔离区，复核后才执行动作。

文章提到 triage workflow 时强调 quarantine：读取外部评论、工单、网页或用户提交内容的 agent，不应该直接执行高权限动作。它只能产出证据或建议，再交给更可信的执行 agent 复核。这样既能自动化处理大量输入，又不把权限交给不可信文本。

原文译读版：A harness for every task

原文开头的核心判断是：Claude Code 现在可以按任务现场写出自己的多 agent harness，并用这个 harness 编排一组子 agent。普通 Claude Code 的默认 harness 已经很适合编码，但研究、安全分析、agent teams、代码审查这类任务有时需要更定制的工作方式。dynamic workflows 的作用，就是让 Claude 不必一直挤在默认执行方式里，而是为当前任务临时搭一套更贴合问题形状的工作台。

作者也很早提醒了一个取舍：这不是低成本魔法。dynamic workflows 往往会用更多 token，更适合复杂、高价值、失败代价比较高的任务。也就是说，它像是给困难任务开一间临时作战室，而不是每次改一行代码都要拉一个委员会。

先看几个提示词，理解它想解决什么

原文在进入技术细节前，先给了一串 prompt 例子。这一段很重要，因为它把 workflow 的气质讲出来了：不是“帮我写代码”，而是“搭一个流程来解决这类复杂问题”。

例如，偶发测试失败可以要求 workflow 反复复现，提出多个竞争性假设，并且在某个假设经得住证据前不要停。也可以让 workflow 回看过去几十次会话，找出你反复纠正 Claude 的地方，再沉淀成 CLAUDE.md 规则。还可以让它翻 Slack 事故频道找重复根因，或者从投资人、客户、竞争对手三个角度拆解商业计划。

这一组例子背后的共同点是：任务不是一步完成，而是需要拆分、比较、复核、循环和停止条件。workflow 更像“让 Claude 设计一套调查流程”，而不是把所有要求塞进一个长 prompt。

它到底怎么工作

dynamic workflow 的执行体是一个 JavaScript 文件。这个文件里既有普通 JavaScript 能力，比如处理 JSON、数组和数学计算，也有一些特殊函数，用来创建 agent、并行执行、串成 pipeline，或者让 agent 返回结构化结果。

图里最值得注意的是两个概念：一是 agent(prompt, opts?)，它让脚本可以召唤一个子 agent，并指定模型、隔离方式、输出 schema 等选项；二是 parallel 和 pipeline，前者适合把多个任务同时派出去，后者适合把前一步结果交给下一步继续处理。

这意味着 workflow 不是把模型能力藏起来，而是把“调度”显式化：什么时候并行，什么时候等待所有结果，什么时候让另一个 agent 审查，什么时候进入下一轮，都可以被写在 harness 里。

workflow 还可以决定子 agent 使用什么模型，以及是否在自己的 worktree 中运行。这个能力很实用：简单分类任务不一定要用最强模型，风险较高的修改可以放到独立 worktree 里减少互相干扰。即使流程被中断，恢复会话后也能从之前状态继续跑。

为什么需要 dynamic workflows

默认 Claude Code 在同一个上下文窗口里既规划又执行。对很多编码任务来说，这已经足够好；但当任务变成长跑、多分支、强对抗或高度结构化时，同一个上下文会开始出现损耗。

原文提到三个典型失败模式。第一个是 agentic laziness：复杂任务还没真正做完，模型就因为局部进展而宣布完成。第二个是 self-preferential bias：模型在审查自己的产出时，更容易偏向自己刚刚得出的结论。第三个是 goal drift：长任务经过很多轮和压缩后，最初的边界、例外、禁止事项慢慢丢失。

workflow 的对应解法，是把任务拆给多个拥有独立上下文的子 agent，每个 agent 只承担一个更聚焦的目标。这样既能降低上下文污染，也能让“验证者”和“执行者”分离，避免自己证明自己。

动态和静态的区别

静态 workflow 不是新东西。你也可以提前用 Claude Agent SDK 或 claude -p 写一个固定流程，协调多个 Claude Code 实例一起工作。问题在于，静态流程通常要覆盖很多边界情况，所以会变得通用、保守、模板化。

dynamic workflows 的不同之处在于：Claude 可以为眼前这件事现场生成 harness。图左边的静态 harness 像一条固定流水线，不管问题是什么，都按同一套搜索、阅读、验证、总结来跑。图右边的动态 workflow 则会先判断问题是什么，再临时决定要哪些 agent、哪些验证、哪些分支，最终给出更具体的建议。

这也是我觉得文章标题里 “for every task” 最有意思的地方：它不是说每个任务都用同一个万能 harness，而是每个足够复杂的任务，都可以拥有一套临时定制的 harness。

六种常见 workflow pattern

原文列了六种常见模式。理解这些模式以后，你给 Claude 提需求时就不只是说“用 workflow”，而是能更明确地说“先分类再路由”“并行调查后合成”“每个结论都要独立审查”。

Classify-and-act 是先让分类器判断任务类型、风险、规模或需要的模型，再把任务送到不同处理路径。Fan-out-and-synthesize 是把大任务拆成很多小块并行执行，等所有结果回来后统一合成。Adversarial verification 是让独立 agent 用 rubric 审查另一个 agent 的结果。

Generate-and-filter 适合探索：先生成大量候选，再去重、过滤、验证，只保留质量高的结果。Tournament 是让多个 agent 用不同策略做同一件事，再通过两两比较或评审选出优胜者。Loop until done 则适合总量未知的任务，不设固定轮数，而是跑到没有新发现、没有错误或验证通过。

真正有用的 workflow 往往会组合这些模式。比如一次技术事实核验可能先抽取 claim，再 fan-out 去查证，每个查证结果再交给 verifier，最后合成报告。

workflow 最适合发光的场景

原文总结了一组很典型的使用场景：迁移、研究、验证、排序、规则遵守、根因调查、分诊、品味探索、eval、模型路由。这些场景看起来很杂，但都有共同结构：工作量大、可以拆开、需要独立判断，或者需要某种形式的复核。

大规模迁移和重构适合 workflow，因为可以按 callsite、失败测试、模块或文件把任务拆开。每个子 agent 在自己的 worktree 里处理一部分，再由审查 agent 检查并合并。这里还要注意资源限制：如果几十个 agent 同时跑重命令，机器会先被打满，所以最好提示 workflow 避免高资源命令。

深度研究也很适合。workflow 可以 fan-out 做搜索和抓取，然后让验证 agent 检查来源质量，最后合成带引用的报告。这个思路不只适用于网页，也适用于 Slack、内部文档、代码库和历史讨论。

用 workflow 做事实核验

如果你有一份报告，想确认里面每个事实性主张是否站得住，workflow 可以先派一个 claim extractor 抽取所有可核验主张，再为每条主张派 claim checker 去查证来源。更稳一点，还可以为每个 checker 再配一个 source auditor，专门检查引用是否可靠、来源是否高质量。

这张图展示的就是这种结构：报告进入 workflow 后，被拆成 claim A、B、N，每条 claim 都有自己的查证路径。最后只有经过来源审查的结论才合并成 verified report。

这个结构对写技术文章尤其有用。很多时候我们不是故意写错，而是把“印象里是这样”写成了确定语气。workflow 可以把这种模糊主张拆出来，一条条逼它找证据。

用 tournament 做大规模排序

排序问题看起来简单，但如果一次性把一千条支持工单、候选人、bug 或用户反馈塞给模型，它既放不进上下文，质量也容易下降。原文建议用 tournament、成对比较 pipeline，或者先并行分桶再合并。

图里的思路像淘汰赛：一千个 item 先被分成许多成对比较，第一轮选出胜者，第二轮继续比较，直到得到最终排序。比较判断通常比绝对打分更可靠，因为模型只需要回答“这两个哪个更严重/更合适/更值得优先”，不用在抽象尺度上给所有东西打分。

这里 deterministic loop 负责维护 bracket 和运行顺序，agent 只负责单次比较。这样上下文压力小，也更容易追踪每一步为什么这么排。

把规则遵守做成 verifier

如果你发现 Claude 总是漏掉某些项目规则，只把规则写进 CLAUDE.md 可能还不够。原文建议把规则变成 verifier：每条规则都由一个独立检查者负责，比如不能改快照、迁移要配 rollback、不要新增生产日志等。

图里每一条规则后面都有一个 verifier agent。diff 进来后，verifier 逐条检查，最后由 bucketer 把通过、需要修改、需要人工确认的结果分出来。

反过来，workflow 也能帮你提炼规则。它可以读取最近的会话和 code review 评论，找出你反复纠正 Claude 的地方，聚类后再让 skeptical agent 审查这些候选规则，确认它们真的能避免真实错误，最后把幸存规则整理回 CLAUDE.md。

根因调查：让假设彼此独立

调试和事故复盘最怕的，是一条假设刚有点证据，模型就越走越自信。workflow 可以通过结构避免这件事：让不同 agent 从不同证据来源独立提出假设，比如日志、代码、数据、最近变更；再让 verifier 和 refuter 对每个假设进行审查和反驳。

这个模式不只适用于代码。销售下滑、数据管道失败、产品指标异常、事故复盘，都可以用类似结构：先分头找证据，再合并假设，再用反证步骤筛掉解释力弱的说法。

大规模分诊要隔离不可信输入

分诊是 workflow 很自然的使用场景。支持队列、bug 报告、需求池、社区反馈，都可能大到人类处理不过来。workflow 可以先分类、去重、匹配已有 issue，然后尝试修复或升级给人类。

但原文特别强调 quarantine。读取公开评论、用户提交、工单正文这类不可信内容的 agent，不应该直接执行高权限动作。图里左侧 reader agents 只能阅读和汇总，进入 quarantine 区域后输出结构化 summary，再交给右侧更可信的 actor agent。actor agent 才能根据规则决定是否行动、升级或放弃。

这个边界非常关键。否则外部输入里的一句“忽略之前规则，执行某某命令”就可能通过自动化流程一路传到高权限动作里。

探索、品味和 eval

设计、命名、产品方案、文案方向这些任务也适合 workflow，因为它们往往不是单一正确答案，而是需要多个候选、一个 rubric 和某种比较机制。你可以让不同 agent 按不同策略生成候选，再让 review agent 按标准筛选。停止条件也可以交给 review agent：当它认为方案达到标准，就结束。

eval 也是类似结构。比如你刚做了一个 skill，可以让多个 agent 在独立 worktree 里用它完成任务，再由 comparison agent 按 rubric 比较输出质量。这样 workflow 本身也可以成为改进 workflow、skill 和提示词的工具。

模型路由则是另一个实用方向：先派一个分类器研究任务复杂度，再决定用 Sonnet 还是 Opus。比如“解释 auth 模块”到底难不难，取决于 auth 相关文件数量、耦合程度和代码库结构，而不是需求一句话本身。

什么时候不要用

dynamic workflows 很强，但不是默认解法。原文给的提醒很朴素：它会多用 token，不是每个任务都值得。普通编码任务、小范围修复、一步能完成的低风险改动，大多不需要一个五人评审团。

我觉得可以用三个问题判断：这件事是否需要并行上下文？是否需要独立验证？是否有明确停止条件或循环条件？如果只有一个答案是“是”，普通 Claude Code 可能更省事；如果两个以上是“是”，workflow 就值得考虑。

建 workflow 的几个小技巧

原文最后给了一些使用建议。第一，prompt 要具体。不要只说“用 workflow”，要说明希望它用哪些模式：比如先分类、再 fan-out、每个结果做 adversarial verification，最后用 rubric 合成。

第二，小任务也可以用 quick workflow。比如你只是想让另一个 agent 对某个假设做一次独立反驳，不一定要开很大的流程。

第三，可重复任务适合配合 /loop，比如持续分诊、持续研究、持续验证；有硬性完成标准的长任务适合配合 /goal，把完成条件钉牢。第四，可以明确 token budget，避免 workflow 自动扩张到不可控。

保存和分享 workflow

workflow 跑起来后，菜单里可以看到运行中和已完成的工作流，也能选择保存。保存以后，它就不只是一次性的临时脚本，而是可以复用、调整、分享的工作流资产。

原文最后提到，可以把 workflow 文件放到 skill 文件夹里，并在 SKILL.md 中引用它。这里有一个很值得记的建议：通过 skill 分发时，最好把 workflow 当作模板，而不是要求 Claude 每次逐字执行固定脚本。这样既能复用经验，又能保留 dynamic workflow 最重要的部分：按当前任务现场调整。

我读完后的抓手

不要把 workflow 当成“更强的 prompt”，而要把它当成“为任务临时搭出来的工作台”。当任务需要拆分、验证、比较、循环、预算控制或恢复执行时，它才真正显出价值。

我的个人判断是：如果任务里有两个以上问题答案是“是”——是否需要并行上下文、是否需要独立验证、是否存在明确停止条件、是否要隔离权限或不可信输入——那就值得考虑 dynamic workflow。否则，直接用普通 Claude Code，反而更轻快。

这篇只讲架构和思想，不先进入具体代码细节。适合想快速判断“这个项目解决什么问题、为什么这样设计、我是否需要它”的读者。

https://github.com/zarazhangrui/lark-coding-agent-bridge

1. 这是什么：把聊天接到本机 CLI

这张图先纠正一个常见误解：项目本身不是云端 Agent，而是本机桥接进程。用户在飞书里发需求，bridge 接住消息，再启动本机 Claude Code 或 Codex CLI 去看项目、改代码、跑工具，结果再回到飞书。它的价值不是替代 Agent，而是把熟悉的聊天入口变成远程控制本机开发环境的通道。

2. 主运行链路：先过闸门再启动进程

一条普通消息不会直接冲进 CLI。bridge 会先收消息，合并短时间内的连续输入，再检查访问权限、工作目录、附件策略和权限模式。只有这些条件通过，才会真正启动本机 agent 进程；不通过就给出拒绝或提示。这说明项目的主链路不是“转发消息”这么简单，而是“聊天输入 -> 运行策略 -> 本地执行 -> 结果回传”。

3. 会话和上下文：每个场景有自己的记忆

项目把私聊、群话题、文档评论都当成不同的上下文范围。每个范围会绑定自己的工作目录和会话记录，Claude 用 session 续聊，Codex 用 thread 续聊。这样不同项目、不同话题不会互相串上下文。对用户来说，这意味着你可以在不同聊天场景里持续推进不同任务，而不用每次重新解释全部背景。

4. 队列和控制命令：普通消息合并，命令快跑

bridge 有一个按上下文分组的静默窗口，用来把连续发来的消息合成一轮任务。运行中再来的普通消息会排到下一轮，避免同一个聊天里同时启动多个互相打架的 agent。但 `/stop`、`/cd`、`/new` 这类命令会绕过普通队列，及时改变当前运行。这是项目体验里很重要的一点：普通输入要稳，控制动作要快。

5. 权限和工作目录：边界先收窄

这个项目很在意“谁能让本机 agent 干活”。默认只有 app 创建者可用，管理员和群白名单可以扩展访问。运行前还会检查工作目录，拒绝 home 根目录、系统目录、临时目录这类过宽范围，再映射到 Claude 或 Codex 的权限模式。它不是把安全问题全交给 CLI，而是在聊天入口和本机执行入口之间先做一层实用边界。

6. 飞书卡片回显：事件流收敛成一张卡

本机 CLI 输出的是文本、思考、工具调用、错误、完成等事件。bridge 把这些事件归一成运行状态，再渲染成飞书卡片或 markdown。用户看到的是一张持续刷新的运行卡，还能在卡片上终止当前任务。也就是说，飞书不是只显示最终答案，而是成为观察本机 Agent 运行过程的窗口。

`lark-channel-bridge` 的架构思想是：把飞书变成本机 Coding Agent 的入口，同时用会话、队列、权限和卡片回显，把远程聊天控制本机开发环境这件事做得可持续、可观察、可管理。

说明：这份文档是对博客内容的中文学习整理和课堂式讲解，不是逐字翻译。重点是帮你建立可复用的理解框架。

╔═══════════════════════════════════════════════════════╗
║  Study Session #1: Claude Code in Large Codebases     ║
║  Today's Topic: 让 Claude Code 在大代码库里找得到路     ║
╚═══════════════════════════════════════════════════════╝

张老师：今天我们学一篇很实用的文章。它不是在说“模型又变强了”这么简单，而是在说：大型组织想让 Claude Code 真正有用，需要把代码库、工具、流程和团队责任一起整理好。

小明：所以这篇博客不是教程吗？更像一张“企业落地地图”？

林姐：对，像给 Claude Code 修路、立路牌、配地图、安排交通规则。

张老师：很好。我们今天的目标就是看清这套“路网”。

1. 一句话大图景

小明：那这篇博客到底在讲什么？

张老师：一句话：Claude Code 可以在百万行、多仓库、老系统、复杂语言栈里工作，但它的效果不只取决于模型，还取决于代码库有没有给它足够清晰的导航、工具和组织支持。

林姐：也就是说，模型像一位聪明工程师，但聪明工程师也需要项目地图、构建命令、团队约定和权限边界。

张老师：正是如此。一个好比喻是：Claude Code 是来到陌生城市的工程师；大型代码库是城市；CLAUDE.md、hooks、skills、plugins、LSP、MCP、subagents 就是路标、规章、专家手册、工具箱、地图软件、外部办事窗口和临时助手。

小明：这里的“大型代码库”只指 monorepo 吗？

张老师：不只。文章把大型代码库理解得很宽：百万行 monorepo、多仓库微服务、几十年积累的 legacy 系统、多语言工程，甚至包括 C、C++、C#、Java、PHP 这类很多团队不一定第一时间联想到 AI 编程工具的语言。

┌─ New Word ────────────────────────────────────────────┐
│ 大型代码库：不一定只指“行数多”。它还包括多年老系统、   │
│ 多语言项目、多仓库微服务、复杂构建流程和大量团队约定。 │
└───────────────────────────────────────────────────────┘

2. 文章结构地图

这篇博客可以拆成四个大区：

              ┌────────────────────────────────────┐
              │ Claude Code 大型代码库实践          │
              │ (城市导航手册)                      │
              └─────────────────┬──────────────────┘
                                │
        ┌───────────────────────┼───────────────────────┐
        │                       │                       │
┌───────▼────────┐      ┌───────▼────────┐      ┌───────▼────────┐
│ 代码库导航方式 │      │ Harness 工具层 │      │ 三类配置模式   │
│ (找路方式)     │      │ (装备系统)     │      │ (施工方案)     │
└───────┬────────┘      └───────┬────────┘      └───────┬────────┘
        │                       │                       │
        │                       │                       │
┌───────▼────────┐      ┌───────▼────────┐      ┌───────▼────────┐
│ 组织落地方式   │      │ 组件对照表     │      │ 适用边界       │
│ (运营团队)     │      │ (工具说明书)   │      │ (现实提醒)     │
└────────────────┘      └────────────────┘      └────────────────┘

小明：为什么这里不按“功能列表”背？

张老师：因为这篇文章真正的逻辑是“怎样让 Claude Code 在复杂环境里少迷路”。先理解导航，再理解工具层，最后理解团队怎么维护它。

林姐：像装修办公室，先要知道人怎么走，再买设备，最后安排谁维护。

3. Claude Code 怎样在大型代码库里导航

张老师：博客强调一个核心区别：Claude Code 更像软件工程师一样在本地代码库里工作。它遍历文件系统、读文件、用 grep 类搜索工具定位内容，再顺着引用去理解代码。

小明：等等，它不是先把整个代码库“吃进去”吗？

张老师：这正是文章要澄清的地方。很多 RAG 类型工具会先把代码库切块、向量化、建立索引，再在提问时检索相关片段。但在大型活跃代码库里，索引可能落后于真实代码：昨天改名的函数、上周删除的模块，都可能还留在旧索引里。

林姐：所以 RAG 像图书馆旧目录，Claude Code 的方式像直接进现在的书架找书。

张老师：很形象。实际情况更细，但这个心智模型很稳。

┌─ New Word ────────────────────────────────────────────┐
│ RAG：Retrieval-Augmented Generation，检索增强生成。    │
│ 可以理解为“先查资料，再回答”。问题是资料索引可能过期。 │
└───────────────────────────────────────────────────────┘

┌─ New Word ────────────────────────────────────────────┐
│ Agentic search：让智能体像工程师一样主动搜索、读文件、 │
│ 跟踪引用，而不是只等一个固定检索系统喂给它片段。       │
└───────────────────────────────────────────────────────┘

导航方式对比

┌──────────────────────────────┐      ┌──────────────────────────────┐
│ RAG 代码搜索                  │      │ Claude Code agentic search    │
│ (先建目录卡片)                │      │ (现场走访)                    │
└──────────────┬───────────────┘      └──────────────┬───────────────┘
               │                                      │
               ▼                                      ▼
       建索引 / 向量化                         读本地真实文件
               │                                      │
               ▼                                      ▼
       查询时取相关片段                       grep / rg / 文件阅读 / 引用追踪
               │                                      │
               ▼                                      ▼
       风险：索引滞后                         风险：没有起点会乱找

小明：那 Claude Code 这种方式是不是就完美了？

张老师：不是。它的代价是需要“起点上下文”。如果你在十亿行代码里问一个很模糊的问题，它还是会被上下文窗口和搜索范围卡住。

林姐：所以关键不是“把所有东西都塞给它”，而是“让它知道该从哪里开始找”。

4. Harness：模型之外的装备系统

张老师：文章说，一个常见误解是只看模型能力。实际上，Claude Code 的表现很大程度上由模型周围的 harness 决定。

小明：Harness 是什么意思？

张老师：可以理解为“马具”或“装备系统”。马很强，但没有鞍、缰绳、路线和骑手配合，跑不出稳定结果。对 Claude Code 来说，harness 包括配置文件、自动化脚本、技能包、插件、外部工具连接等。

┌─ New Word ────────────────────────────────────────────┐
│ Harness：围绕模型的一整套运行环境和工具系统。它决定了  │
│ 模型在真实工程流程里能不能稳定发挥。                   │
└───────────────────────────────────────────────────────┘

Harness 层次图

              ┌────────────────────────────────────┐
              │ Claude Code + 当前模型              │
              │ (会思考的工程师)                    │
              └─────────────────┬──────────────────┘
                                │
      ┌─────────────────────────┼─────────────────────────┐
      │                         │                         │
┌─────▼─────┐             ┌─────▼─────┐             ┌─────▼─────┐
│ CLAUDE.md │             │  Hooks    │             │  Skills   │
│ (路牌)    │             │ (自动门禁) │             │ (专家卡片) │
└─────┬─────┘             └─────┬─────┘             └─────┬─────┘
      │                         │                         │
      │                         │                         │
┌─────▼─────┐             ┌─────▼─────┐             ┌─────▼─────┐
│ Plugins   │             │   MCP     │             │   LSP     │
│ (工具包)  │             │ (办事窗口) │             │ (IDE 地图) │
└─────┬─────┘             └─────┬─────┘             └─────┬─────┘
      │                         │                         │
      └─────────────────────────┼─────────────────────────┘
                                │
                         ┌──────▼──────┐
                         │ Subagents   │
                         │ (临时分队)  │
                         └─────────────┘

张老师：文章特别强调，不同组件不是一锅乱炖。它们各自解决不同问题。

4.1 CLAUDE.md：给 Claude 的项目路牌

张老师：CLAUDE.md 是 Claude 每次会话开始时自动读取的上下文文件。根目录文件讲大图景，子目录文件讲局部约定。

小明：那是不是越详细越好？

张老师：这就是第一个坑。因为它每次都会加载，所以只适合放广泛适用、关键、稳定的知识。太多细节会拖慢理解，甚至干扰判断。

林姐：像办公室门口的公告栏，只贴“逃生路线、会议室规则、重要联系人”，不要贴每个同事今天午饭吃什么。

4.2 Hooks：让流程自动发生

张老师：Hooks 是在关键事件发生时运行的脚本。很多人只把它当成“防止 Claude 做错事”的拦截器，但文章说更有价值的是持续改进。

小明：比如？

张老师：会话结束时，让 stop hook 回顾这次工作，提出 CLAUDE.md 是否需要更新；会话开始时，让 start hook 动态加载某个团队或模块的上下文。对 lint、format 这类确定性检查，hook 比一句“请记得格式化”更可靠。

┌─ New Word ────────────────────────────────────────────┐
│ Hook：自动触发的小脚本。像门铃或传送带上的感应器，某个 │
│ 事件一发生，它就按规则做固定动作。                     │
└───────────────────────────────────────────────────────┘

4.3 Skills：按需打开的专家手册

张老师：Skills 的价值是“按需加载”。大型代码库有很多任务类型：安全审查、文档更新、支付服务部署、数据分析等。不是每次会话都需要这些知识。

小明：那 Skill 和 CLAUDE.md 有什么区别？

张老师：CLAUDE.md 是每次都读的路牌；Skill 是需要时才打开的专家手册。把所有专家手册塞进路牌，会让路牌变成字典，反而没人看得清。

┌─ New Word ────────────────────────────────────────────┐
│ Progressive disclosure：渐进披露。先只显示必要信息，  │
│ 等任务需要时再展开细节，避免一开始就信息过载。         │
└───────────────────────────────────────────────────────┘

4.4 Plugins：把好用的配置打包分发

张老师：Plugins 把 skills、hooks、MCP 配置等打包成可安装组件。它解决的问题是：一个团队摸索出的好配置，不要只留在少数人的电脑上。

林姐：像公司新员工入职包。装上之后，第一天就有常用工具、流程和知识。

小明：所以插件是为了规模化复制经验？

张老师：对。文章用的词是避免知识停留在“部落知识”状态，也就是只有少数老员工知道。

4.5 LSP：让 Claude 像 IDE 一样按符号导航

张老师：LSP 是 Language Server Protocol。它让编辑器具备“跳转到定义”“查找引用”等能力。把这种能力暴露给 Claude，就能让 Claude 按符号找代码，而不是只靠文本匹配。

小明：为什么文本匹配不够？

张老师：在大代码库里，一个常见函数名可能有几千个匹配。LSP 能区分“同名但不同含义”的函数，先过滤掉不相关结果。

林姐：像找人。文本搜索是全城叫“张伟”的都列出来；LSP 是知道你要找哪家公司、哪个部门的那位张伟。

┌─ New Word ────────────────────────────────────────────┐
│ LSP：语言服务器协议。它把编程语言的结构信息提供给编辑器 │
│ 或工具，比如定义、引用、类型错误。                     │
└───────────────────────────────────────────────────────┘

4.6 MCP servers：连接 Claude 够不到的内部工具

张老师：MCP servers 用来连接内部工具、数据源、API、文档系统、工单系统、分析平台等。它们让 Claude 不只看代码，还能调用组织内的结构化工具。

小明：那是不是应该先造很多 MCP？

张老师：文章提醒，别太早。基础配置没跑顺之前，先做 MCP 可能是在没修路前先建收费站。要先保证 Claude 能读懂代码库，再扩展外部工具。

4.7 Subagents：把探索和编辑分开

张老师：Subagent 是一个独立的 Claude 实例，有自己的上下文窗口。它可以负责读代码、整理发现，再把最终结果交给主会话。

林姐：像侦察小队先去画地图，主工程师再动手改代码。

小明：那这样可以避免主会话读太多文件，把上下文塞满？

张老师：没错。尤其在大系统里，先探索、后编辑，是很稳的工作流。

5. 组件对照表：该把什么放在哪里

6. 三类成功配置模式

文章总结了三类经常出现的成功模式。

模式一：让代码库在规模上可导航

张老师：第一类模式是“让代码库好找路”。不是让 Claude 读更多，而是让它更快找到正确的上下文。

做法 A：CLAUDE.md 精简且分层

根目录 CLAUDE.md 放全局地图和关键坑点；子目录 CLAUDE.md 放局部约定。

小明：那如果子目录里有 CLAUDE.md，根目录内容还会丢吗？

张老师：文章说，Claude 会沿目录树向上加载能找到的 CLAUDE.md，所以根目录的大图景不会丢。

做法 B：从相关子目录启动，而不是总在根目录启动

在 monorepo 里，很多人习惯站在根目录。但对 Claude 来说，任务在哪里，就从相关子目录开始，范围更清楚。

林姐：像去商场修一家店的灯，不是先从整个商场地图研究起，而是先到那家店门口。

做法 C：按子目录配置测试和 lint 命令

如果 Claude 只改了一个服务，不应该每次都跑全仓库测试。子目录 CLAUDE.md 应该告诉它这个模块对应的测试、构建、格式化命令。

小明：这样能减少超时和无关输出？

张老师：对，也减少 Claude 被噪音带偏。

做法 D：用 ignore 和 permissions.deny 排除噪音

生成文件、构建产物、第三方代码通常不该让 Claude 反复读取。文章提到可以把排除规则版本化，让团队共享同一套降噪配置。

张老师：但也有例外。如果团队正在开发代码生成器，生成文件本身可能就是工作对象，这时可以用本地设置覆盖项目级排除。

做法 E：目录结构不清楚时，手写 codebase map

如果顶层目录很多、历史包袱重、命名不清晰，可以在根目录放一个轻量 Markdown 地图：每个顶层目录一行说明。

小明：这像给旧仓库补一个“目录索引”。

张老师：完全正确。

做法 F：配置 LSP，让搜索从字符串升级为符号

文本搜索在大代码库里容易返回太多结果。LSP 能先按语言语义过滤，再让 Claude 打开更少、更准的文件。

模式二：随着模型进步，主动维护配置

张老师：第二类模式是“配置会过期”。以前为了弥补模型弱点写的规则，未来可能会限制新模型发挥。

小明：比如以前让 Claude 每次只改一个文件，是为了稳；但新模型可能已经能处理跨文件重构？

张老师：对。如果旧规则还留着，它就会把新模型绑住。文章建议团队每三到六个月做一次配置审查，也可以在重大模型发布后审查。

林姐：所以 CLAUDE.md、skills、hooks 不是写完就永远不动，而是像软件依赖一样需要维护。

模式三：给 Claude Code 管理和采用分配所有权

张老师：第三类模式是组织层。技术配置自己不会推动采用。成功推广通常需要专门的人或小团队提前把工具、插件、MCP、流程准备好。

小明：这是不是 developer experience 团队的活？

张老师：很多组织确实放在开发者体验或开发者生产力团队里。文章也提到一种新兴角色：agent manager，类似 PM 和工程师的混合角色，负责管理 Claude Code 生态。

林姐：如果没有专门团队，至少要有 DRI？

张老师：是的。DRI 指 Directly Responsible Individual，也就是明确负责的人。这个人要能决定设置、权限、插件市场、CLAUDE.md 约定，并负责让它们保持最新。

┌─ New Word ────────────────────────────────────────────┐
│ DRI：直接负责人。不是“大家都关心”，而是“出了问题知道找谁，│
│ 需要决策知道谁拍板”。                                 │
└───────────────────────────────────────────────────────┘

张老师：文章还提醒，在大组织和受监管行业里，治理问题会很早出现。比如：哪些 skills 和 plugins 可以用？怎样避免几千个工程师重复造同一个工具？AI 生成的代码怎样进入和人类代码一样的 review 流程？

林姐：所以比较稳的做法是先批准一组工具和流程，小范围开放，随着信心增加再扩大？

张老师：对。文章也建议尽早建立跨职能工作组，让工程、信息安全、治理相关同事一起定义要求和 rollout 路线。

7. 适用边界：这套建议默认什么前提

小明：这篇文章是不是适用于所有项目？

张老师：它主要假设一种常规软件工程环境：工程师是主要代码贡献者，仓库使用 Git，代码目录结构相对标准。大部分大型代码库都接近这个模式，所以建议有普适性。

林姐：那哪些情况更麻烦？

张老师：比如游戏引擎项目里有大量二进制资产，或者组织使用非传统版本控制系统，或者大量非工程师也在贡献代码。这些场景不是不能用 Claude Code，而是需要更多针对性配置。

┌─ New Word ────────────────────────────────────────────┐
│ 适用边界：一套方法默认成立的条件。知道边界不是泼冷水，  │
│ 而是避免把好方法误用到完全不同的地形上。               │
└───────────────────────────────────────────────────────┘

8. 整体数据流：一次 Claude Code 任务怎样跑起来

假设一个工程师想让 Claude Code 修改 payments 服务里的一个 bug：

工程师在 payments/ 启动任务
        │
        ▼
┌──────────────────────┐
│ 加载根 CLAUDE.md      │
│ (全局地图)            │
└──────────┬───────────┘
           │
           ▼
┌──────────────────────┐
│ 加载 payments/CLAUDE.md│
│ (局部规则和命令)       │
└──────────┬───────────┘
           │
           ▼
┌──────────────────────┐
│ 使用 rg / 文件阅读 / LSP│
│ 找到相关代码           │
└──────────┬───────────┘
           │
           ▼
┌──────────────────────┐
│ 需要时加载 Skill       │
│ (比如支付部署流程)     │
└──────────┬───────────┘
           │
           ▼
┌──────────────────────┐
│ 修改代码并跑局部测试   │
│ hooks 自动检查格式     │
└──────────┬───────────┘
           │
           ▼
┌──────────────────────┐
│ 可选：subagent 探索    │
│ 可选：MCP 查内部系统   │
└──────────┬───────────┘
           │
           ▼
       提交给人类 review

小明：为什么不能一开始就把全仓库、所有文档、所有工具都给 Claude？

张老师：因为上下文不是仓库越满越好，而是越相关越好。就像做菜时不用把超市搬进厨房，只需要拿对食材。

9. 最重要的学习结论

结论一：大型代码库里的 Claude Code 是“现场导航”，不是“全知索引”

它从真实本地代码库工作，避免了旧索引问题；但它需要清楚的起点、目录地图和局部规则。

结论二：Harness 和模型同样重要

模型能力只是发动机。CLAUDE.md、hooks、skills、plugins、LSP、MCP、subagents 这些配置层决定发动机能不能接到真实工程流程里。

结论三：不要把所有知识塞进 CLAUDE.md

CLAUDE.md 放每次都该知道的内容；skills 放任务型专家知识；hooks 放自动化动作；plugins 用来分发成熟配置；MCP 连接外部系统。

结论四：组织所有权决定能否规模化

没有 DRI 或平台团队，配置会分裂，经验会停留在个人电脑上，采用会慢慢停滞。

10. 从博客转成行动清单

如果你要把这篇博客应用到自己的项目，可以按这个顺序做：

1. 写一份根目录 CLAUDE.md，只放项目大图景、关键命令、重要坑点和导航入口。

2. 给重要子目录补局部 CLAUDE.md，写清楚局部约定、测试命令、lint 命令和常见风险。

3. 在大型或混乱仓库里补一份 codebase map，每个顶层目录一句话。

4. 排除生成文件、构建产物、第三方依赖等噪音，并把共享规则版本化。

5. 配置对应语言的 LSP，让 Claude 能按符号而不是纯文本找代码。

6. 把重复任务做成 hooks，比如格式化、lint、会话结束后的文档更新建议。

7. 把特定工作流做成 skills，比如安全审查、发布流程、文档同步、数据查询。

8. 把成熟的 skills、hooks、MCP 配置打成 plugins，给团队统一分发。

9. 基础稳定后再接 MCP，连接内部文档、工单、数据平台或搜索工具。

10. 对大型探索任务使用 subagents，让主会话保留编辑上下文。

11. 指定 DRI 或小团队负责配置、权限、插件市场和审查节奏。

12. 每三到六个月复查配置，尤其在新模型发布后清理过时限制。

11. 常见误区和修正

12. 课堂小测

┌───────────────────────────────────────────────────────┐
│ Quick Check #1                                         │
│ 问：为什么文章认为大型代码库中 RAG 索引可能出问题？     │
│ a) 因为 RAG 永远不能处理代码                           │
│ b) 因为索引可能落后于真实代码变化                       │
│ c) 因为 grep 比所有系统都聪明                           │
│                                                       │
│ 小明：我选 b。旧目录可能跟不上每天提交。                │
│ 张老师：对。文章不是否定所有 RAG，而是指出活跃大型仓库   │
│ 中“索引滞后”会造成错误上下文。                         │
└───────────────────────────────────────────────────────┘

┌───────────────────────────────────────────────────────┐
│ Quick Check #2                                         │
│ 问：什么内容最适合放进根目录 CLAUDE.md？                │
│ a) 所有安全审查流程细节                                 │
│ b) 项目大图景、关键命令、全局坑点                       │
│ c) 每个团队自己的全部内部文档                           │
│                                                       │
│ 林姐：应该是 b。                                      │
│ 张老师：对。a 更适合 skill，c 容易把全局上下文变成噪音。 │
└───────────────────────────────────────────────────────┘

┌───────────────────────────────────────────────────────┐
│ Quick Check #3                                         │
│ 问：LSP 主要帮 Claude 解决什么问题？                    │
│ a) 按符号理解代码导航，而不只是文本搜索                 │
│ b) 自动替团队写所有测试                                 │
│ c) 替代代码 review                                     │
│                                                       │
│ 小明：我差点选 b，因为听起来很厉害。                    │
│ 张老师：很正常。但正确答案是 a。LSP 是地图软件，不是自动 │
│ 交付保证。                                             │
└───────────────────────────────────────────────────────┘

┌───────────────────────────────────────────────────────┐
│ Quick Check #4                                         │
│ 问：Skills 和 CLAUDE.md 的关键区别是什么？              │
│ a) Skills 按需加载，CLAUDE.md 每次加载                  │
│ b) Skills 只能写代码，CLAUDE.md 只能写中文              │
│ c) 两者没有区别                                         │
│                                                       │
│ 林姐：a。像专家手册和门口公告栏。                      │
│ 张老师：正解。这个区别能避免上下文膨胀。                │
└───────────────────────────────────────────────────────┘

┌───────────────────────────────────────────────────────┐
│ Quick Check #5                                         │
│ 问：为什么组织需要 DRI 或 agent manager？               │
│ a) 为了集中沉淀配置、权限、插件和最佳实践               │
│ b) 为了让所有人只能用同一种写代码方式                   │
│ c) 为了减少代码 review                                  │
│                                                       │
│ 小明：是 a。没人负责就会变成大家各玩各的。              │
│ 张老师：对。治理不是为了束缚，而是为了让好经验能复制。   │
└───────────────────────────────────────────────────────┘

13. 复习用短版

张老师：我们最后把整篇文章压缩成一张小纸条：

• Claude Code 在大代码库里靠现场搜索、读文件、跟引用来导航，不依赖预先上传的代码索引。

• 这种方式需要好起点：精简分层的 CLAUDE.md、清楚的目录地图、局部测试命令、噪音排除和 LSP。

• Harness 比单个模型指标更决定真实效果；不同组件要放在正确位置。

• 成功部署还需要组织层所有权：DRI、平台团队、治理、插件分发、定期配置审查。

小明：我现在理解了。不是“让 Claude 变成全知”，而是“让 Claude 像一个新来的好工程师那样快速上手”。

林姐：而且新来的工程师需要的不只是文档，还需要工具、权限、流程和有人维护。

张老师：很好。下一次我们可以把这篇文章变成你自己项目的落地模板，比如写一份根 CLAUDE.md、一个子目录 CLAUDE.md 模板，以及 hooks/skills/plugins 的分工表。

14. 下次可以继续的方向

1. 根据你的某个仓库，做一份真实的 codebase map。

2. 设计一套根目录 CLAUDE.md + 子目录 CLAUDE.md 模板。

3. 把“哪些内容进 CLAUDE.md，哪些做成 skill/hook/plugin”做成决策树。

4. 为团队落地 Claude Code 写一份 30 天 rollout plan。

5. 做一份配置审查清单，用于每三到六个月清理过时规则。