The faster AI writes code, the less an engineer can afford to focus on the code itself. The scarce skill is shifting from “getting every line right” to “designing a system that keeps producing correct code”: constrain generation with rules, validate the rules with a small experiment, let adversarial agents actively hunt for problems, and let the compiler and tests act as the judge. This is my write-up and reflection after reading Anthropic’s “How Anthropic runs large-scale code migrations with Claude Code.”
I recently read a piece Anthropic published: “How Anthropic runs large-scale code migrations with Claude Code.”
The article describes how they used Claude Code and many AI agents to run several large code migrations, including:
The article is short, but its density of practices — around rule-writing, task decomposition, quality verification, adversarial review, and cost control — is very high.
I’ve done several small-to-medium software service migrations myself, usually in the tens of thousands of lines.
Once you’ve done a few of these, you realize very clearly: code migration is far more than “translating old code into new code.”
The genuinely hard problems usually include:
The challenges behind these questions aren’t purely about coding ability — they’re about project management, architecture, task decomposition, test planning, and risk control.
As AI’s coding ability grows stronger, migration speed really can improve by an order of magnitude. But at the same time, the quality-assurance problem can be amplified even further.
When AI can generate tens or hundreds of thousands of lines in a short time, a human can no longer review the whole thing file by file, pull request by pull request.
At that point, the question an engineer must solve shifts from:
Is every line the AI wrote correct?
to:
How do I keep the AI from drifting? How do I build an objective verification mechanism? How do I make errors get discovered, classified, and fixed automatically? How do I use AI to run the old-vs-new comparison testing better?
Ordinary engineers rarely get to take part in a million-line language migration. The Bun migration Anthropic disclosed here cost roughly $165,000 at API pricing alone, consuming 5.9 billion uncached input tokens and 690 million output tokens.
So this is not just a product-marketing piece — it can also be read as a very expensive large-scale AI engineering experiment report.
And it genuinely contains many practices you can apply directly to everyday development.
In the past, a large language migration usually meant a multi-year project.
The team had to maintain two codebases for a long time:
If the migration failed, the team ended up not with a better system, but with two systems to maintain.
So in the past, only a truly severe problem was enough to justify a large language migration — for example:
AI agents changed this cost model.
Anthropic offers an interesting judgment in the article:
Now the worst case of a failed migration might just be deleting the branch and doing it again.
This does not mean code migration has become cheap.
The Bun migration still cost about $165,000 at API pricing. But compared with projects that used to run for years and burn millions of dollars of engineering resources, the cost of trial and error has dropped dramatically.
Worth noting: even this successful Bun migration saw 19 regressions surface after merge (all since fixed). That’s exactly the point of this piece — once migration gets fast, regression and quality verification don’t become optional; they become more critical.
So some problems that “weren’t worth migrating” before may now be worth recalculating the ROI on.
For example, an internal Python tool at Anthropic used to be built per platform — roughly 8 minutes each — for a total wait of about 30 minutes across the build matrix. After migrating to TypeScript, compile time dropped to about two seconds, startup got 6x faster, and a whole separate deployment pipeline could be retired.
AI doesn’t just make migration faster — it lowers the bar for a company to re-evaluate its technical debt.
Anthropic states a core idea in the article:
You don’t fix the code. You fix the process (loop) that produced the code.
This one line can almost summarize the entire AI migration methodology.
In traditional development, when an engineer finds a bug, they usually edit the corresponding file.
But in a large-scale agent migration, if dozens of files exhibit the same class of error, editing them one by one does not solve the real problem.
What actually needs to change might be:
The right move is not to have an engineer hand-edit dozens of files, but to:
This is one of the biggest differences between agent engineering and traditional coding.
The engineer’s focus starts to shift from “producing code directly” to “designing a system that can keep producing correct code.”
Before the real migration, you first need a “judge” that can evaluate both the old and the new system.
That judge might be:
A good judge must satisfy two conditions:
First, it passes normally on the old system.
Second, when the system is deliberately broken, it must be able to detect the problem.
The article puts it bluntly:
A judge that can’t detect failure isn’t a judge.
In reality, many old projects have tests that rely on internal functions or language features and can’t be reused directly in the new language.
So you first have to classify the tests:
Lacking a complete test suite doesn’t mean you can’t migrate.
The Python-to-TypeScript project built only seven real business scenarios, then ran them on both the old and new systems and diffed the output of every command.
The point here isn’t how many tests you have — it’s that you must establish an objective standard both sides accept.
The old system itself is the new system’s most important ground truth.
This is the most important — and most engineer-time-consuming — phase of the whole migration.
1. The rulebook
The rulebook tells all migration agents:
If the goal is to preserve the existing structure, the rulebook may mostly be a set of language and type mapping rules.
If the migration also involves architectural refactoring, the rulebook is closer to a full design document.
It’s not an ordinary prompt — it’s an engineering spec every agent must obey.
2. The dependency graph
Large-scale migration needs heavy parallelism.
But parallelism requires knowing:
So Anthropic first uses a deterministic script to analyze code dependencies, then has an agent review and fix the dependency graph.
There’s an important principle here:
Don’t leave to the model’s guessing what a deterministic program can do.
3. The difference list
There are inevitable semantic differences between the old and new languages. For example:
These problems can’t be solved by simple syntax substitution and must go into the difference list ahead of time.
The rulebook defines the default approach; the difference list records the cases the default rules don’t cover.
I think this is one of the most worth-learning practices in the whole article.
Anthropic doesn’t migrate all the code the moment the rules are done. Instead, it first picks a small set of representative files and runs a small-scale migration experiment.
In the Bun migration, they set up:
From this experiment alone, they caught two serious problems ahead of time.
If those problems hadn’t been exposed at the small scale but had instead spread across all 1,448 files, the cost of fixing them later would have been enormous.
Even more counterintuitive:
The code the experiment produces should be thrown away.
Because the point of this phase isn’t to make migration progress — it’s to validate the migration rules.
This is a lot like a spike, PoC, or pilot in everyday development, except AI makes such experiments much cheaper.
Exposing rule problems with a little code first, then running massively in parallel, is more reliable than chasing migration progress from the start.
Only after the rules are validated does the real full-code migration begin.
Anthropic’s basic loop is:
Implement → Review → Fix
Multiple implementation agents work on different files or modules in parallel.
To control cost, high-throughput implementation work can go to smaller, cheaper models; complex rule design, architectural judgment, and code review go to stronger models.
The migration queue is managed by a script, not by the agent’s own memory. For example:
Designed this way, the migration naturally supports pause and resume.
Wherever an agent can’t decide how to migrate, it marks it uniformly:
// TODO(port): <reason>
After that, compiler errors, smoke-test crashes, and test failures automatically become the next batch of fix tasks.
The queue doesn’t need long-term manual maintenance, because the failures themselves keep generating new tasks.
Once the initial migration is done, the compilation phase begins.
Here you have to decide where to place the compiler based on the project’s characteristics.
TypeScript compiles fast, so it can sit inside each agent’s loop.
A full build of a large Rust project can take minutes, so the Bun migration didn’t have each agent run compilation independently. Instead, a unified orchestration script ran the full build, then handed the error list out to multiple fix agents.
This design also reflects cost control. If every agent repeatedly ran the full build, it would waste huge amounts of CPU, time, tokens, context, and CI resources.
So they set up a single build daemon.
Only this process can rebuild the program. Other agents only submit patches, and the build daemon batches the patches, does a unified build, and re-runs the relevant tests.
Essentially, it centralizes the most expensive operation instead of letting a swarm of agents repeat it.
Passing compilation doesn’t mean the program runs. Next you run smoke tests to find:
Here, too, you can’t look at a single error at a time.
If dozens of crashes come from the same root cause, you should fix the upstream rule or architecture, not have dozens of agents submit ad-hoc patches separately.
Anthropic’s approach is to cluster problems by root cause first, then have adversarial review agents check the classification and the fix plan.
The final step is confirming the old and new systems truly behave the same.
By now, the new code has been translated, compiled, smoke-tested, and had its basic problems fixed. But to prove the migration succeeded, you still need to compare real behavior.
Anthropic splits the test tasks up. Each failing test is handled by an independent fix agent that looks at, all at once:
After the fix, an adversarial review agent checks the change.
The Python-to-TypeScript migration also used seven real usage scenarios to call both systems, then diffed the output item by item.
After that, Claude autonomously designed an end-to-end test suite and ran, fixed, and re-ran it for four nights in a row, surfacing edge cases that a hand-written scenario list would struggle to anticipate.
This is exactly where I think AI is well suited to shine:
not just having AI generate business code, but having AI:
AI can generate code fast, but migration rules, architectural boundaries, and verification standards still require heavy engineer time.
Anthropic’s conclusion:
Human effort should be front-loaded as much as possible.
The parts that cost engineers the most time are:
Once these are done, the rest is mostly letting the task queue converge.
This is exactly the opposite of how many people use coding agents.
Many people first have AI generate a lot of code, then slowly patch in rules after problems appear. But for large tasks, the more sensible order is:
Spend time defining the system first, then let AI execute fast.
The article repeatedly mentions adversarial review.
An implementation agent’s goal is to finish the task.
A review agent’s goal should not be to help the implementation agent prove itself right — it should actively hunt for:
Anthropic has two review agents check the same result in mutually independent contexts. If they disagree, a third agent decides.
This kind of mechanism suits not just code migration but also everyday work: architecture design reviews, data migrations, API refactors, database upgrades, framework upgrades, large code cleanups, security reviews, and test-plan reviews.
Not every agent should play “collaborator.” Some agents should be explicitly designed as skeptics, opponents, and breakers.
Facing a million lines of AI-generated code, no human can review it line by line. What engineers should really watch is:
In other words: you no longer just review the code — you review the loop that generates the code.
This doesn’t mean code review is unimportant; it means human attention should focus on high-risk code and systemic problems. Ordinary, repetitive, bulk code relies more on compilers, static checks, tests, diffs, contracts, adversarial agents, and automated gates.
The article discusses cost control in many places. For example:
This shows that in a large-scale agent system, model choice, task queue, build pipeline, and verification mechanism can no longer be considered separately.
Together they determine the project’s completion speed, token cost, infrastructure cost, error-convergence speed, and final quality.
Cost optimization for AI agents isn’t just “switch to a cheaper model” — it’s redesigning the entire execution pipeline.
Most engineers won’t migrate a million lines, but this method still applies to ordinary development.
For a Java version upgrade, a Spring Boot upgrade, a database migration, an API refactor, or a front-end framework migration, you can use a similar flow:
First, build a rules file. Make explicit: which patterns must be replaced; which interfaces must not change; which directories may not be modified; which compatibility behaviors must be preserved; which exception-handling styles must be unified; and what conditions require stopping and reporting.
Second, build an old-vs-new comparison tool. For the same input, call both systems and compare: return values, error codes, logs, database changes, message output, performance, and memory and resource usage.
Third, run a throwaway experiment first. Pick a few representative modules to migrate. Don’t rush to keep the code — use the experiment to find out whether the rules are complete, whether the agent understands the task, whether the tests can catch errors, whether the module split is reasonable, and whether the prompt is ambiguous.
Fourth, have different agents play different roles. At minimum distinguish: implementation agent, rule-review agent, code-review agent, test-design agent, behavior-comparison agent, and risk-review agent.
Fifth, fix the rule that produces the errors. When multiple modules show the same problem, don’t fix them one by one. First decide whether to change the rule, change the prompt, change the task split, add tests, add static checks, or change the model division of labor.
This may be the most important mindset shift when using coding agents at scale.
AI agents are making some once-high-risk, long-cycle engineering projects feasible again.
But the biggest takeaway for me isn’t “Claude can generate a million lines in two weeks.”
What’s really worth noting is how Anthropic designed a complete engineering control system around AI’s uncertainty:
The faster AI writes code, the less an engineer can afford to focus on the code alone.
The more important skill for future engineers may be:
Designing constraints, building judges, organizing agents, and constructing an engineering loop that keeps finding and fixing errors.
For any engineer using Claude Code, Codex, Cursor, or another coding agent, I strongly recommend reading the original. Even without an immediate large-migration need, it’s worth seeing how Anthropic designs prompts, rules, reviews, tests, and agent workflows.
These methods apply not only to language migration, but also to everyday refactoring, architecture upgrades, and complex feature development.
Original: How Anthropic runs large-scale code migrations with Claude Code (authored by / copyright Anthropic; this post is my write-up and personal reflection).
]]>AI 写代码的速度越快，工程师越不能只关注代码本身。真正稀缺的能力，正在从“写对每一行代码”转向“设计一套能持续生产正确代码的系统”：用规则约束生成、用小规模实验验证规则、用对抗性 Agent 主动找问题、用编译器和测试当裁判。这篇是我读 Anthropic《How Anthropic runs large-scale code migrations with Claude Code》后的整理与思考。
最近读了 Anthropic 发布的一篇文章：《How Anthropic runs large-scale code migrations with Claude Code》。
文章分享了他们如何利用 Claude Code 和多个 AI Agent，完成多次大型代码迁移。其中包括：
文章篇幅不长，但里面关于规则制定、任务拆分、质量验证、对抗审查和成本控制的实践，信息密度非常高。
我自己做过多次中小型软件服务迁移，代码规模通常在几万行左右。
做过这类项目之后，会很清楚地意识到：代码迁移远远不是“把旧代码翻译成新代码”这么简单。
真正困难的问题通常包括：
这些问题背后涉及的其实不是单纯的编码能力，而是项目管理、架构设计、任务拆解、测试计划和风险控制。
随着 AI 编程能力越来越强，代码迁移的速度确实可能获得数量级的提升。但与此同时，质量保障问题反而可能被进一步放大。
当 AI 可以在短时间内生成几万甚至几十万行代码时，人已经不可能逐个文件、逐个 Pull Request 地进行完整审查。
这时，工程师需要解决的问题就从：
AI 写的每一行代码是否正确？
转变为：
如何约束 AI 不跑偏？ 如何建立客观的验证机制？ 如何让错误能够被自动发现、分类和修复？ 如何利用 AI 更好地完成新旧系统的对比测试？
普通工程师很少有机会参与百万行代码级别的语言迁移。Anthropic 这次公开的 Bun 迁移，仅按照 API 价格计算，就消耗了大约 16.5 万美元，使用了 59 亿个未缓存输入 Token 和 6.9 亿个输出 Token。
因此，这不仅是一篇产品宣传文章，也可以看作一份非常昂贵的大规模 AI 工程实验报告。
而且，里面确实有不少可以直接应用到日常开发工作的实践。
过去，大型语言迁移通常意味着持续数年的项目。
团队需要长期维护两套代码：
如果迁移失败，团队得到的可能不是一个更好的系统，而是两套都需要维护的系统。
因此，过去只有非常严重的问题，才足以推动一次大型语言迁移，例如：
AI Agent 改变了这个成本模型。
Anthropic 在文章中给出了一个很有意思的判断：
现在迁移失败的最坏结果，可能只是删除分支，然后重新再做一次。
这并不意味着代码迁移已经变得便宜。
Bun 的迁移按照 API 定价仍然花费约 16.5 万美元。但相比过去可能持续数年、消耗数百万美元工程资源的项目，试错成本已经显著降低。
值得一提的是，即便是这次成功的 Bun 迁移，合并后仍然出现了 19 个回归问题（目前已全部修复）。这恰好印证了本文的判断：迁移变快之后，回归和质量验证不是变得可有可无，而是变得更加关键。
因此，一些过去“不值得迁移”的问题，现在可能已经值得重新计算投入产出比。
例如，Anthropic 内部的一个 Python 工具，过去需要针对不同平台分别构建，每个平台大约 8 分钟，完整构建矩阵大约需要等待 30 分钟。迁移到 TypeScript 后，编译时间缩短到约两秒，启动速度提升了六倍，同时还可以下线一套独立的部署流程。
AI 不只是让迁移变快，也降低了企业重新评估技术债的门槛。
Anthropic 在文章中提出了一个核心观点：
You don’t fix the code. You fix the process (loop) that produced the code.
翻译过来就是：
不要只修复代码，而要修复生成这些代码的流程（循环）。
这句话几乎可以概括整套 AI 迁移方法。
在传统开发中，当工程师发现一个 Bug，通常会修改对应的文件。
但在大规模 Agent 迁移中，如果几十个文件都出现了同一类错误，逐个修改文件并不能解决真正的问题。
真正需要修改的可能是：
正确的做法不是让工程师手动修改几十个文件，而是：
这也是 Agent 工程和传统编码最大的区别之一。
工程师的工作重点，开始从“直接生产代码”，转向“设计能够持续生产正确代码的系统”。
正式迁移之前，首先需要建立一个能够同时评价旧系统和新系统的“裁判”。
这个裁判可能是：
一个好的裁判必须满足两个条件：
第一，它能够在旧系统上正常通过。
第二，当系统被故意破坏时，它必须能够发现问题。
文章中的说法很直接：
无法发现故障的裁判，就不是真正的裁判。
现实中，很多旧项目的测试依赖内部函数或语言特性，无法直接复用到新的语言中。
这时需要先对测试进行分类：
如果没有完整测试套件，也不代表无法迁移。
Python 到 TypeScript 的项目只构建了七个真实业务场景，然后同时在新旧系统中执行，对每条命令的输出进行 Diff。
这里的关键不是一定要有多少测试，而是必须建立一个双方都认可的客观标准。
旧系统本身，就是新系统最重要的 Ground Truth。
这是整个迁移过程中最重要、也最消耗工程师时间的阶段。
1. 规则手册
规则手册用于告诉所有迁移 Agent：
如果迁移目标是保持原有结构，规则手册可能主要是一组语言和类型的映射规则。
如果迁移同时涉及架构重构，规则手册就更接近一份完整的设计文档。
它不是一个普通 Prompt，而是所有 Agent 必须遵守的工程规范。
2. 依赖图
大规模迁移需要高度并行。
但并行的前提是知道：
因此，Anthropic 会先利用确定性脚本分析代码依赖，再由 Agent 审查和修复依赖图。
这里有一个很重要的原则：
能用确定性程序完成的事情，不要完全交给模型猜测。
3. 差异清单
旧语言和新语言之间必然存在语义差异。例如：
这些无法通过简单语法替换解决的问题，需要提前放入差异清单。
规则手册定义默认做法，差异清单记录默认规则无法覆盖的情况。
我认为这是整篇文章里最值得学习的实践之一。
Anthropic 不会在规则完成后立即迁移全部代码，而是先选择少量具有代表性的文件，进行一次小规模迁移实验。
Bun 的迁移中，他们安排：
仅仅通过这次实验，他们就提前发现了两个严重问题。
如果这些问题没有在小规模阶段暴露，而是直接扩散到全部 1448 个文件，后面的修复成本会非常高。
更加反直觉的是：
实验产生的代码应该直接丢弃。
因为这个阶段的目的不是完成迁移进度，而是验证迁移规则。
这和日常开发中的 Spike、PoC 或试点项目很像，但 AI 让这种实验的成本变得更低。
先用少量代码暴露规则问题，再大规模并行执行，比一开始追求迁移进度更可靠。
规则经过验证后，才开始真正迁移全部代码。
Anthropic 使用的基本循环是：
Implement → Review → Fix 实现 → 审查 → 修复
多个实现 Agent 并行处理不同文件或模块。
为了控制成本，高吞吐量的实现工作可以交给较小、较便宜的模型；复杂规则设计、架构判断和代码审查，则交给能力更强的模型。
迁移队列由脚本管理，而不是依赖 Agent 自己记忆。例如：
这样设计后，迁移过程天然可以暂停和恢复。
Agent 无法确定如何迁移的地方，则统一标记：
// TODO(port): <reason>
之后，编译器错误、Smoke Test 崩溃和测试失败，会自动成为下一批修复任务。
队列不需要人工长期维护，因为失败本身就在不断生成新的任务。
代码完成初步迁移后，开始进入编译阶段。
这里需要根据项目特点决定编译器放在什么位置。
TypeScript 编译速度较快，可以放入每个 Agent 的执行循环。
Rust 大型项目的完整编译可能需要几分钟，因此 Bun 的迁移没有让每个 Agent 独立运行编译，而是由统一的编排脚本执行完整构建，再把错误列表分配给多个修复 Agent。
这个设计也体现了成本控制。如果每个 Agent 都重复执行完整构建，会浪费大量 CPU、时间、Token、上下文和 CI 资源。
因此，他们设置了一个统一的 Build Daemon。
只有这个进程可以重新构建程序。其他 Agent 只负责提交补丁，由 Build Daemon 对补丁进行批量合并、统一构建并重新执行相关测试。
它本质上是把最昂贵的操作集中管理，而不是让大量 Agent 重复执行。
通过编译不代表程序能够正常运行。接下来需要执行 Smoke Test，发现：
这里同样不能只看单个错误。
如果几十个崩溃来自同一个根因，就应该修改上游规则或架构，而不是让几十个 Agent 分别提交临时补丁。
Anthropic 的做法是先按根因对问题进行聚类，再由对抗性审查 Agent 检查问题分类和修复方案。
最后一步，是确认新旧系统的行为真正一致。
此时，新代码已经完成翻译、编译、Smoke Test 和基本问题修复。但要证明迁移成功，仍然需要对比真实行为。
Anthropic 会将测试任务拆分执行。每个失败测试由独立的修复 Agent 同时查看：
修复之后，再由对抗性审查 Agent 检查修改。
Python 到 TypeScript 的迁移，还使用七个真实使用场景分别调用两个系统，然后对输出逐项进行 Diff。
之后，Claude 又自动设计了一套端到端测试，连续四个晚上运行、修复并重新执行，从而发现了一些人工场景列表很难提前想到的边缘问题。
这也是我认为 AI 非常适合发挥能力的地方：
不是只让 AI 生成业务代码，而是让 AI：
AI 可以快速生成代码，但迁移规则、架构边界和验证标准仍然需要工程师投入大量时间。
Anthropic 的结论是：
人工投入应该尽量前置。
最花费工程师时间的部分是：
一旦这些工作完成，后面的过程主要是让任务队列不断收敛。
这和很多人使用 Coding Agent 的习惯恰好相反。
很多人会先让 AI 大量生成代码，发现问题后再慢慢补规则。但对于大型任务，更合理的顺序是：
先花时间定义系统，再让 AI 快速执行。
文章中多次提到 Adversarial Review，也就是对抗性审查。
实现 Agent 的目标是完成任务。
审查 Agent 的目标不应该是帮助实现 Agent 证明自己正确，而应该主动寻找：
Anthropic 会让两个审查 Agent 在相互独立的上下文中检查同一份结果。如果两者意见不一致，再交给第三个 Agent 判断。
这类机制不只适合代码迁移，也很适合日常工作中的：架构设计评审、数据迁移、API 重构、数据库升级、框架升级、大型代码清理、安全审查、测试计划评审。
Agent 不应该全部扮演“协作者”。有些 Agent 应该被明确设计成怀疑者、反对者和破坏者。
面对百万行 AI 生成代码，人不可能逐行审查。工程师真正应该关注的是：
也就是说，不再只审查代码，而是审查生成代码的 Loop。
这并不代表代码审查不重要，而是人的注意力应该集中在高风险代码和系统性问题上。普通、重复、大批量的代码，则更多依靠编译器、静态检查、测试、Diff、契约、对抗性 Agent 和自动化门禁。
文章很多地方都在讨论如何控制成本。例如：
这说明在大规模 Agent 系统中，模型选择、任务队列、构建流程和验证机制已经不能分开考虑。
它们共同决定了：项目的完成速度、Token 成本、基础设施成本、错误收敛速度和最终质量。
AI Agent 的成本优化，不只是“换一个便宜模型”，而是重新设计整个执行流程。
大多数工程师不会迁移百万行代码，但这套方法仍然可以应用到普通开发中。
例如进行 Java 版本升级、Spring Boot 升级、数据库迁移、API 重构或前端框架迁移时，可以采用类似流程：
第一，先建立规则文件。 明确：哪些模式必须替换；哪些接口不能改变；哪些目录不允许修改；哪些兼容行为必须保留；哪些异常处理方式需要统一；什么情况必须停止并报告。
第二，建立新旧系统对比工具。 相同输入分别调用新旧系统，比较：返回值、错误码、日志、数据库变更、消息输出、性能、内存和资源使用。
第三，先做一次可丢弃实验。 选择几个典型模块进行迁移。不要急着保留代码，而是通过实验发现：规则是否完整；Agent 是否理解任务；测试是否能够发现错误；模块拆分是否合理；Prompt 是否存在歧义。
第四，让不同 Agent 扮演不同角色。 至少区分：实现 Agent、规则审查 Agent、代码审查 Agent、测试设计 Agent、行为对比 Agent、风险审查 Agent。
第五，修复产生错误的规则。 当多个模块出现相同问题时，不要逐个修改。先判断是否应该：修改规则、修改 Prompt、修改任务拆分、增加测试、增加静态检查、改变模型分工。
这可能才是大规模使用 Coding Agent 时最重要的思维变化。
AI Agent 正在让一些过去风险极高、周期极长的工程项目重新变得可行。
但文章给我的最大启发，并不是“Claude 可以在两周内生成百万行代码”。
真正值得关注的是，Anthropic 如何围绕 AI 的不确定性，设计了一套完整的工程控制系统：
AI 写代码的速度越快，工程师越不能只关注代码本身。
未来工程师更重要的能力，可能是：
设计约束、建立裁判、组织 Agent，并构建一个能够持续发现和修复错误的工程闭环。
对于正在使用 Claude Code、Codex、Cursor 或其他 Coding Agent 的工程师，我非常推荐阅读原文。即使暂时没有大型代码迁移需求，也可以看看 Anthropic 如何设计 Prompt、Rule、Review、Test 和 Agent Workflow。
这些方法不仅适用于语言迁移，对日常的软件重构、架构升级和复杂功能开发同样很有参考价值。
原文： How Anthropic runs large-scale code migrations with Claude Code（作者 / 版权归 Anthropic；本文为读后整理与个人思考）
]]>In the Coding Agent era, the core of knowledge management is not “remember more.” It is “load on demand.” What matters is not context size, but context routing: load the right knowledge at the right stage, make every judgment evidence-backed, and gradually turn repeated experience into automated checks. This is a key step from prompt engineering to agent system engineering.
I have been thinking about a question: how should knowledge be managed in a Coding Agent development workflow?
When many teams start using agents, their first instinct is to give the agent more context: more docs, more memory, more rules, more historical cases.
But the result is not always better. An agent is not a human. More context does not automatically make it smarter. It can create new problems:
So knowledge management for Coding Agents should not only be organized by topic, such as “metrics docs,” “security docs,” or “test docs.”
The more important dimension is access pattern:
In other words, the core question is not “what do we know?” It is “what does this task need loaded to support judgment?”
The pattern I like is:
Index → Route → Body
That means: read the index first, route second, and only then load the necessary body.
An agent should not read the whole knowledge base at startup. A better approach is:
Take a team-code-review review loop as an example. It can parse the PR, get changed files, then classify the change:
If the PR touches locale formatting files, load the locale spec.
If the PR touches a shared metric, load shared metric rules and relevant lessons.
If it only changes test config, do not load the locale spec.
This distinction matters.
A low-quality loop says: “I give the agent every document and hope it can figure it out.”
A sustainable loop says: “I ask the agent to classify first, then only load the knowledge needed for the current judgment.”
The first merely piles up context. The second builds a reusable engineering system.
In a Coding Agent workflow, I tend to separate knowledge into several layers. Each layer should have its own loading moment instead of entering the global prompt by default.
This is the most important layer, and often the earliest one to load.
It answers the question: what must not be broken?
For example:
If a PR changes access-control metadata, the review loop must load the access-control contract before reviewing.
If this kind of issue is wrong, the impact is usually not a local bug. It is a broken system boundary.
But if the PR does not touch these boundaries at all, there is no need to load them.
Invariants should be loaded early, but only when the relevant boundary is touched.
A map is not supposed to explain every detail. Its job is to help the agent route.
A good map should be small enough to scan quickly.
For example:
If files under shared_metrics/ change,
load the shared metric rule,
and run the metric validation path.
That is much better than:
Here is everything we know about metrics.
The first is an executable routing rule. The second is an information pile.
A map is not the knowledge body. A map is the routing table that keeps the agent from reading the wrong documents.
A spec is the correctness oracle.
When a PR claims to change a behavior, the agent should not judge correctness from memory. It should load the corresponding spec.
If a PR changes date formatting behavior, the review loop should load the formatting spec and check:
If the spec does not define the expected behavior, the agent should not invent a standard.
A better finding is:
The expected behavior is not defined. Add a spec before treating this as correct.
That is more engineering-oriented than judging from experience.
A procedure answers: how should this kind of task be performed in this project?
For example, the main code review command should not contain every review checklist. It is better suited for orchestration.
Specific checklists can be split into skills:
This keeps the main workflow light, while domain-specific gotchas live inside the corresponding skill.
The main workflow owns orchestration. Skills own procedural detail.
That is a key part of making agent workflows maintainable.
The value of ADRs is that they stop agents from “fixing” an intentional design.
Many times, when an agent sees complex code, it instinctively wants to simplify it. Sometimes that is right. But sometimes the complexity is intentional: compatibility, cross-system contracts, performance constraints, or migration strategy.
So ADRs should be triggered when a PR touches:
ADRs should not be loaded every time. They should be hit through an index and loaded when related areas change.
Otherwise, the agent can get distracted by historical design discussions in irrelevant situations.
Plans are useful, but they are temporary scaffolding.
They fit:
But a plan should not stay in the default context forever.
Once the work is complete, durable knowledge should move elsewhere:
A simple rule:
Plans expire.
Specs and ADRs survive.
A plan is scaffolding, not the building.
The most common problem with lessons is that they are too generic.
A bad lesson:
Be careful with metrics.
A good lesson:
When a PR hides a shared metric,
check whether that metric is reused by multiple surfaces before approving.
A good lesson has a trigger.
In a review loop, the agent should scan lesson headers first, not load every lesson body. If changed files hit a trigger, then load the full content. If not, skip it.
That preserves team memory without polluting the context window.
A gotcha is a small trap inside a specific procedure.
For example:
If only one skill uses a gotcha, put it inside that skill instead of the global prompt.
The rule is:
If only one procedure needs it,
keep it inside that procedure.
That keeps the global prompt from becoming bloated.
A case record captures one specific historical run:
Its value is audit, dispute review, and issue tracing.
But it should not become default context for every review.
For example, the last PR’s review report should not influence the next PR by default, unless the current task is explicitly resuming the same PR or directly references that historical case.
Historical cases are evidence, not standing knowledge.
The end state of knowledge management is not a longer prompt.
The best knowledge should eventually become executable checks:
A lesson is only a reminder:
Remember to check X.
A test is a guarantee:
X cannot regress silently.
If the agent manually checks the same issue every time, that knowledge has not finished maturing. It should be upgraded into an automated check.
In a multi-agent review loop, subagents can expand coverage.
For example, one subagent can use an external review tool, another can use internal project review skills, and a third can focus on test coverage.
But the lead agent must not merely merge the results.
It must:
Subagents produce candidates.
The lead agent should produce evidence-backed findings.
This is critical. Otherwise, multi-agent review easily becomes “several agents producing noise together.”
The real value of a Coding Agent workflow is not that it reviews one PR for you. It is that it can keep compounding knowledge.
The ideal loop looks like this:
incident
→ distilled lesson
→ routed skill gotcha or review rule
→ automated check
→ less prose in the prompt
In practice:
That is the key to agent loop compounding.
Do not make the agent remember everything. Make it:
Many AI Coding practices are still stuck at “give the agent more context.”
But from an engineering-system point of view, the real issue is not context size. It is context routing.
An agent should not feel like a junior engineer buried under documents. It should behave like an engineering system with process, indexes, and verification.
I increasingly think that high-quality coding agent workflows will compete on three things, not only model capability:
The model generates candidates. The workflow constrains the path. The verification mechanism proves the result.
Without these structures, a stronger agent may simply produce more uncertain output faster.
With these structures, an agent can move from a one-off tool to a compounding engineering system.
The goal of knowledge management for Coding Agents is not to make them remember everything.
The goal is:
This is a key step from prompt engineering to agent system engineering.
A mature agent workflow is not a very long prompt. It is a system that routes, verifies, and learns.
]]>Coding Agent 时代，知识管理的核心不是“记住更多”，而是“按需加载”。真正重要的不是 context size，而是 context routing：让正确的知识，在正确的阶段，被正确加载；让每个判断都有证据；让重复经验逐步变成自动化检查。这也是从 prompt engineering 走向 agent system engineering 的关键一步。
最近在思考一个问题：Coding Agent 的开发流程里，知识应该怎么管理？
很多团队在使用 agent 时，第一反应是给它更多上下文：更多文档、更多 memory、更多规则、更多历史案例。
但实际效果不一定更好。因为 agent 不是人。上下文给得越多，它不一定越聪明，反而可能出现几个问题：
所以，Coding Agent 的知识管理，不应该只按 topic 分类，比如“metrics 文档”“security 文档”“test 文档”。
更关键的是按 access pattern 管理：
换句话说，核心问题不是“我们知道什么”，而是“当前这个任务，需要加载什么知识来支持判断”。
我比较认同的模式是：
Index → Route → Body
也就是：先看索引，再做路由，最后只加载必要正文。
Agent 不应该一上来就把整个知识库读一遍。更合理的做法是：
以一个 team-code-review 这样的 review loop 为例，它可以先解析 PR，拿到 changed files，然后判断这次改动属于哪类：
如果 PR 改的是 locale formatting 文件，就加载 locale spec。
如果 PR 改的是 shared metric，就加载 shared metric 相关规则和历史 lesson。
如果只是 test config 调整，就不需要加载 locale spec。
这个区别非常重要。
一个低质量 loop 是：“我把所有文档都塞给 agent，希望它自己判断。”
一个可持续进化的 loop 是：“我让 agent 先分类，再只加载当前判断所需的知识。”
前者只是堆上下文，后者才是在构建一个可复用的工程系统。
在 Coding Agent workflow 里，我倾向于把知识分成几类。每一类知识都应该有自己的加载时机，而不是默认进入全局 prompt。
这是最重要、也应该最早加载的一层。
它回答的问题是：什么东西不能被破坏？
比如：
如果一个 PR 改了 access-control metadata，review loop 必须在 review 前加载 access-control contract。
因为这类问题一旦出错，影响通常不是局部 bug，而是系统边界被破坏。
但如果当前 PR 完全不涉及这些边界，就没有必要加载。
不变量应该被早加载，但只在相关边界被触碰时加载。
Map 的作用不是解释所有细节，而是帮助 agent 路由。
好的 map 应该足够小，能被快速扫描。
比如：
如果 shared_metrics/ 目录下的文件发生变化，
加载 shared metric rule，
并执行 metric validation path。
这比下面这种写法好很多：
这里是我们关于 metrics 的全部知识。
前者是可执行的路由规则。后者只是信息堆积。
Map 不是知识正文，Map 是让 agent 少读错文档的路由表。
Spec 是 correctness oracle。
当一个 PR 声称修改了某个行为，agent 不应该凭记忆判断这个行为是否正确，而应该加载对应 spec。
比如 PR 改了 date formatting 行为，review loop 应该加载 formatting spec，然后检查：
如果 spec 里没有定义预期行为，agent 不应该自己编一个标准。
更合理的 finding 是：
当前 expected behavior 没有被定义，建议补充 spec。
这比“凭经验判断对错”更工程化。
Procedure 回答的是：在这个项目里，这类任务应该怎么执行？
比如 code review 主命令不应该包含所有 review checklist。它更适合负责 orchestration。
具体 checklist 可以拆到不同 skill：
这样主流程保持轻量，具体领域的 gotchas 也可以放在对应 skill 里。
主流程管编排，skill 管过程细节。
这其实也是 agent workflow 可维护性的关键。
ADR 的价值在于避免 agent “修复”一个 intentional design。
很多时候，agent 看到复杂代码，会本能地想简化。这有时是对的，但有时这个复杂度是历史兼容、跨系统契约、性能约束或迁移策略下的有意选择。
所以当 PR 触碰这些内容时，应该触发 ADR：
ADR 不应该每次都加载。它应该通过索引命中，在相关区域发生变化时再加载。
否则 agent 很容易在无关场景里被历史设计讨论干扰。
Plan 很有用，但它是临时脚手架。
它适合用在：
但 plan 不应该长期留在默认上下文里。
一旦工作完成，里面的 durable knowledge 应该沉淀到不同地方：
一个简单原则是：
Plans expire.
Specs and ADRs survive.
Plan 是脚手架，不是建筑本身。
Lesson 最常见的问题是太泛。
不好的 lesson：
Be careful with metrics.
好的 lesson：
When a PR hides a shared metric,
check whether that metric is reused by multiple surfaces before approving.
好的 lesson 一定有 trigger。
在 review loop 里，agent 应该先扫描 lesson header，而不是加载所有 lesson body。如果 changed files 命中了 trigger，再加载完整内容。如果没命中，就跳过。
这样既保留了团队记忆，又不会污染上下文窗口。
Gotcha 是某个 procedure 内部的小陷阱。
比如：
如果一个 gotcha 只在某个 skill 中使用，就应该放在这个 skill 里，而不是放到全局 prompt。
原则是：
If only one procedure needs it,
keep it inside that procedure.
这样可以避免全局 prompt 越来越臃肿。
Case record 记录的是一次具体历史运行：
它的价值在于审计、争议复盘、问题追踪。
但它不应该成为每次 review 默认加载的上下文。
比如上一次 PR 的 review report，不应该默认影响下一次 PR。除非当前任务明确是在 resume 同一个 PR，或者当前问题直接引用了那个历史 case。
历史案例是 evidence，不是 standing knowledge。
知识管理的终点，不是让 prompt 越写越长。
真正好的知识，最后应该沉淀成可执行检查：
Lesson 只是提醒：
Remember to check X.
Test 才是保障：
X cannot regress silently.
如果 agent 每次都在人工检查同一个问题，那说明这个知识还没有沉淀完成。它应该被升级成自动化检查。
在 multi-agent review loop 里，subagents 可以扩大覆盖面。
比如一个 subagent 使用外部 review 工具，另一个 subagent 使用项目内部 review skill，第三个 subagent 专门看测试覆盖。
但最终 lead agent 不能只是合并结果。
它必须负责：
Subagent 生成的是 candidates。
Lead agent 产出的应该是 evidence-backed findings。
这点非常关键。否则 multi-agent review 很容易变成“多个 agent 一起制造噪音”。
我认为 Coding Agent workflow 真正有价值的地方，不是一次性帮你 review 一个 PR，而是它可以把知识持续沉淀下来。
比较理想的闭环是：
incident
→ distilled lesson
→ routed skill gotcha or review rule
→ automated check
→ less prose in the prompt
也就是：
这才是 agent loop compound 的关键。
不是让 agent 记住所有东西，而是让它：
现在很多 AI Coding 实践还停留在“给 agent 更多上下文”的阶段。
但从工程系统角度看，真正重要的不是 context size，而是 context routing。
Agent 不应该像一个被塞满文档的新人。它更应该像一个有流程、有索引、有验证机制的工程系统。
我越来越觉得，未来高质量的 coding agent workflow，核心竞争力不只是模型能力，而是三件事：
模型负责生成候选方案。Workflow 负责约束路径。验证机制负责证明结果。
如果没有这些结构，agent 越强，可能只是更快地产生更多不确定输出。
如果有这些结构，agent 才能从一次性工具，变成可以持续复利的工程系统。
Coding Agent 的知识管理，目标不是让它记住一切。
目标是：
这也是从 prompt engineering 走向 agent system engineering 的关键一步。
真正成熟的 agent workflow，不是一个很长的 prompt，而是一个会路由、会验证、会沉淀的系统。
]]>I recently came across an interesting open-source project: Skills. As of 2026-06-28, the GitHub API showed 149,182 stars. Its author, Matt Pocock, is well known in the frontend and TypeScript world. But what interests me most about this repo is not a specific prompt. It is that the repo turns strong engineering workflows into reusable Agent Skills.
Today I want to focus on one Skill that I think is especially worth studying: improve-codebase-architecture.
In short, it asks an agent to run an architecture diagnosis over a codebase.
It does not simply tell the model, “give me some refactoring ideas.” Instead, it defines a concrete process:
CONTEXT.md and ADRs to understand domain language and existing decisionsThe value is that it does not hand “architecture review” to one free-form reasoning pass. It breaks the review into steps that can be repeated.
I think this Skill points to an important direction in AI Coding:
A good Agent Skill is not really Prompt Engineering. It is Workflow Engineering.
A rough prompt might look like this:
Please analyze this project's architecture and suggest refactors.
A more mature workflow defines the sequence:
Collect Context
↓
Understand Domain Language
↓
Inspect Architecture Friction
↓
Generate Candidates
↓
Visualize Tradeoffs
↓
Grill One Decision
↓
Record Context / ADR
The first relies on the model improvising. The second encodes the order, checkpoints, and decision constraints of an experienced engineer.
That is why I find it more valuable than “a good architecture-analysis prompt.”
Many agent failures are not caused by weak model capability. They come from fuzzy goals.
improve-codebase-architecture has a very specific target: scan a codebase for deepening opportunities, output a readable visual HTML report, then let the user choose one candidate for deeper discussion.
Two constraints matter:
That keeps the agent from sliding from “discover problems” into “refactor a bunch of files.” Architecture work is especially vulnerable to this kind of scope drift: the problem has not been aligned, but the solution is already being implemented.
This Skill starts by reading CONTEXT.md and ADRs. That detail matters.
Code tells the agent what the system currently looks like, but many key decisions do not live in code:
If that knowledge only lives in people’s heads, agents will repeatedly suggest ideas that have already been rejected.
So I increasingly believe this:
An agent’s ceiling is largely determined by the quality of its context.
More context is not automatically better. The context needs to be complete, accurate, and structured. CONTEXT.md captures domain language. ADRs capture historical decisions. Together, they give the agent a more realistic engineering environment.
The most interesting part of this Skill is that the architecture report is not the end.
After the report is generated, the user chooses a candidate and the agent enters /grilling: it walks through constraints, dependencies, the shape of the module, what should sit behind the seam, and which tests should survive.
That is very close to how we make important design decisions in real engineering work:
Propose a solution
↓
Put it under pressure
↓
Expose hidden assumptions
↓
Adjust boundaries and tradeoffs
↓
Only then make a decision
Code review matters. Agent decision review matters too. A single reasoning pass can easily confuse “sounds reasonable” with “actually fits this system.” A grilling or critique loop forces the agent to surface assumptions and inspect them one by one.
If a Skill only emits advice, its value is limited.
improve-codebase-architecture requires an HTML report, and each candidate must include concrete files, problem, solution, benefits, and before/after diagrams. That makes the output inspectable:
I would pair this kind of architecture analysis with /grilling and ADRs to form a complete loop:
Generate report
↓
Choose candidate
↓
Grill the decision
↓
Refine the proposal
↓
Record ADR / update domain context
The next time an agent enters the repo, it does not have to rediscover the same history.
If you are exploring AI Coding, I would not only run the Skill. I would study it as a workflow design example.
1. Write an entry goal for complex tasks.
Do not just write “help me refactor this.” A better goal is: “only scan and produce candidate architecture issues; do not edit code; every candidate must include files, problem, solution, risk, and recommendation strength.”
2. Prepare a CONTEXT.md for the project.
Write down the core domain concepts. Make it clear which words are business concepts and which are merely implementation details.
3. Keep writing ADRs.
For every important architecture choice, record why you chose it, why you rejected the alternatives, and which tradeoffs you knowingly accepted. ADRs are not only for past readers. They give future humans and agents decision context.
4. Run a grilling loop for important proposals.
Ask the agent to do more than produce an answer. Make it accept pressure: what did it miss, which assumptions lack evidence, is the benefit large enough, and is there a simpler solution?
5. Turn outputs into inspectable artifacts.
Reports, tables, diffs, ADRs, and issue lists are easier to review and collaborate on than a free-form block of prose.
Besides improve-codebase-architecture, I would also look at these related Skills in the repo:
grill-with-docs: grill a proposal while also building domain language and ADRs.to-prd: turn the current discussion into a PRD.to-issues: break a plan into independently executable issues.tdd: turn the red-green-refactor loop into an agent workflow.Together, these Skills show the same direction: make agents less like better chatbots, and more like reliable executors of engineering workflows.
I increasingly feel that the dividing line in AI Coding is not only model capability. It is whether you can design strong workflows.
We used to keep a lot of engineering judgment in our heads: clarify the requirement first, inspect the architecture with context, review important decisions, verify before refactoring, and write down historical tradeoffs in ADRs.
Now these practices can be encoded as Skills.
In other words:
The thing worth saving is not the prompt. It is the workflow.
The future difference between engineers may not be only who writes code faster. It may be who can package good engineering practice into repeatable, composable, reviewable workflows.
The valuable part of improve-codebase-architecture is not only that it can generate an architecture report. It is that it simulates the full architecture-review process of a senior engineer:
Read context
↓
Use shared language to find architecture friction
↓
Produce an inspectable report
↓
Choose one candidate
↓
Question and refine the design
↓
Preserve the decision as long-term context
If you are exploring AI Coding, I recommend reading the implementation of this Skill, not just running it. The truly valuable part is hidden in the workflow design.
Source repo: mattpocock/skills
Recommended reading: improve-codebase-architecture/SKILL.md
最近看到一个很有意思的开源项目：Skills。截至 2026-06-28，我通过 GitHub API 查到它已经有 149,182 stars。作者 Matt Pocock 在前端和 TypeScript 圈很有影响力，但这个仓库让我更感兴趣的地方，不是某个具体 prompt，而是它把优秀工程师的工作流程沉淀成了一套套可复用的 Agent Skill。
今天重点推荐其中一个我觉得很值得学习的 Skill：improve-codebase-architecture。
简单说，它会让 Agent 对一个代码仓库做一次架构诊断。
它不是上来就让模型“给我一些重构建议”，而是先规定了明确流程：
CONTEXT.md 和 ADR，理解已有领域语言和历史决策这个流程的价值在于：它没有把“架构评审”交给一次自由发挥的推理，而是把评审拆成了可以重复执行的步骤。
我觉得这个 Skill 代表了 AI Coding 里一个很重要的方向：
优秀的 Agent Skill，本质上不是 Prompt Engineering，而是 Workflow Engineering。
一个粗糙的 prompt 可能是：
请帮我分析这个项目的架构，并给出重构建议。
而一个更成熟的 workflow 会规定：
Collect Context
↓
Understand Domain Language
↓
Inspect Architecture Friction
↓
Generate Candidates
↓
Visualize Tradeoffs
↓
Grill One Decision
↓
Record Context / ADR
前者依赖模型临场发挥，后者把资深工程师的工作顺序、检查点和决策约束都写进了流程。
这也是为什么我觉得它比“一个好用的架构分析 prompt”更值得学习。
很多 Agent 失败，并不是模型能力不够，而是目标定义过于模糊。
improve-codebase-architecture 的目标很具体：扫描代码库里的 deepening opportunities，输出一份可读的可视化 HTML 报告，然后让用户选择一个候选项继续深入。
注意这里有两个关键约束：
这让 Agent 不会从“发现问题”一路滑到“顺手重构一堆文件”。架构工作最怕这种边界漂移：问题还没对齐，方案已经开始落地。
这个 Skill 开始前会读 CONTEXT.md 和 ADR。这个细节很关键。
代码只能告诉 Agent 当前系统“长什么样”，但很多关键决策并不在代码里：
这些信息如果只存在人的脑子里，Agent 很容易反复给出已经被否定过的建议。
所以我越来越认同一点：
Agent 的能力上限，很大程度上取决于上下文质量。
上下文不是越多越好，而是要完整、准确、结构化。CONTEXT.md 负责领域语言，ADR 负责历史决策，它们共同给 Agent 一个更接近真实工程现场的判断环境。
这个 Skill 最有意思的地方，是它没有把架构报告当成终点。
报告生成后，它会让用户选择一个候选项，然后进入 /grilling：围绕约束、依赖、模块形状、接缝后面应该藏什么、哪些测试应该保留，继续一层层追问。
这其实很接近我们日常做重要设计时的过程：
先提出方案
↓
再被严格追问
↓
暴露隐藏假设
↓
修正边界和取舍
↓
最后才形成决策
代码评审重要，Agent 的决策评审同样重要。单次推理很容易把“看起来合理”误当成“真的适合当前系统”。通过 grilling 或类似的 critique loop，可以让 Agent 把自己的假设摊开，再逐个检查。
如果一个 Skill 只输出一段建议，它的价值其实有限。
improve-codebase-architecture 强制输出 HTML 报告，并要求每个候选项都包含具体文件、问题、方案、收益和 before/after diagram。这让结果至少可以被人检查：
我会建议把这类架构分析和 /grilling、ADR 一起使用，形成一个完整闭环：
生成报告
↓
选择候选项
↓
严格追问
↓
修正方案
↓
记录 ADR / 更新领域上下文
这样下一次 Agent 再进入这个仓库时，它不需要重新猜一遍历史背景。
如果你也在探索 AI Coding，我建议不只是运行这个仓库里的 Skill，而是把它当成 workflow 设计样本来学。
1. 给复杂任务写入口目标。
不要只写“帮我重构一下”。更好的目标是：“只扫描并产出候选架构问题，不改代码；每个候选项必须包含文件、问题、方案、风险和推荐强度。”
2. 为项目准备一个 CONTEXT.md。
把领域里的核心概念写进去。哪些词是业务概念，哪些词只是代码实现细节，要让 Agent 分得清。
3. 坚持写 ADR。
只要做了重要架构选择，就记录：为什么选它、为什么不选别的、已知 tradeoff 是什么。ADR 不是给过去的人看的，是给未来的人类和 Agent 提供决策上下文。
4. 重要方案都跑一轮 grilling。
让 Agent 不只是给答案，还要接受追问：遗漏了什么？哪些假设没有证据？收益是否足够大？有没有更简单方案？
5. 把输出改成可检查的 artifact。
报告、表格、diff、ADR、issue 列表，都比一段自由文本更适合复盘和协作。
除了 improve-codebase-architecture，我也建议顺手看一下这个仓库里的几个相关 Skill：
grill-with-docs：在追问方案的同时沉淀领域语言和 ADR。to-prd：把当前讨论整理成 PRD。to-issues：把计划拆成可以独立执行的 issues。tdd：把红绿重构循环固化成 Agent 工作方式。这些 Skill 共同体现了同一个方向：不是让 Agent “更会聊天”，而是让 Agent 更稳定地执行工程流程。
最近越来越感觉，AI Coding 的分水岭不只是模型能力，而是你能不能设计出好的工作流。
过去我们把很多工程经验放在脑子里：需求要先问清楚、架构要先看上下文、重要决策要被 review、重构前要有验证、历史取舍要写 ADR。
现在这些经验可以被写成 Skill。
换句话说：
真正值得沉淀的不是 Prompt，而是 Workflow。
未来工程师之间的差异，可能不只是“谁写代码更快”，而是谁更会把优秀工程实践封装成可重复、可组合、可审查的工作流。
improve-codebase-architecture 值得学习的地方，不只是它能帮你生成一份架构诊断报告，而是它模拟了一位资深工程师完成架构评审的完整过程：
读上下文
↓
用统一语言识别架构摩擦
↓
产出可检查报告
↓
选择候选方案
↓
继续追问和修正
↓
沉淀为长期上下文
如果你正在探索 AI Coding，我会推荐认真阅读这个 Skill 的实现过程，而不只是直接运行它。因为真正有价值的部分，藏在 workflow 设计里。
原仓库：mattpocock/skills
推荐阅读：improve-codebase-architecture/SKILL.md
Anthropic recently shipped Claude Code Dynamic Workflows: instead of a single agent working in one context, Claude Code can write a bespoke harness for the task at hand — a JavaScript workflow that orchestrates multiple subagents. After reading the post and trying it, my main takeaway is this: the things we used to write into prompts (“please check carefully”, “don’t skip the tests”) are turning into structured execution flows. This is a feature walkthrough plus my own thoughts. Source: A harness for every task: Dynamic Workflows in Claude Code.
In one line: Claude Code can write its own harness on the fly, custom-built for the task. It runs a JavaScript workflow whose special functions spawn and coordinate subagents, rather than cramming everything into a single context window.
Those subagents can have their own context windows and focused, isolated goals; you can decide which model each one uses, and even whether each runs in its own worktree. The workflow is plain JavaScript (JSON, Math, Array, and so on) and supports resuming after an interruption.
The post lists six core orchestration patterns:
Plain coding tasks are already a strong suit for Claude Code, but as a task gets complex and the chain gets long, a single context starts to strain: everything is crammed into one window and detail overflows or gets lost. Against that backdrop, the post explicitly names three single-context failure modes:
Dynamic Workflows are designed to push these down using multiple independent contexts and a structured flow.
It suits complex, high-value, long-chain tasks rather than simple code edits. The directions the post recommends, plus scenarios of my own:
In short: whenever a task needs decomposition, parallelism, verification, and synthesis, Dynamic Workflows have room to work.
The biggest shift, I think, is this: AI coding is moving from prompt-driven to workflow-driven.
We used to mostly write prompts — “check step by step”, “don’t skip tests”, “please review this.” Those are really repeated pleas to the same single context. Dynamic Workflows turn those requests into a more stable execution structure: plan first, then decompose, run multiple agents in parallel, cross-verify with independent agents, synthesize at the end, and loop if the condition isn’t met.
That makes the AI feel less like a single assistant and more like a small engineering team you can assemble on demand.
After a quick trial, my sense is that the agent’s built-in harness ability has gone up another level.
Its most immediate value is relieving context-window pressure on complex tasks: hand different subtasks to different agents with their own isolated contexts, instead of cramming all the information into one window.
More importantly, quality. Letting the context that did the work also grade it is unreliable; only a separate, independent context escapes the self-certification bias. One agent implements, another reviews against a checklist, a third synthesizes the verdict — that is exactly the point of the adversarial-verification pattern.
What I think is most worth exploring next is the Dynamic Workflows + Skills combination: distill a team’s recurring processes into skills — schema-change checks, SQL review, migration checklist, release notes, regression tests, incident analysis, PR-review rubric — then use Dynamic Workflows to chain those skills into a more automated, reusable engineering flow. This may be the key step in an AI assistant evolving from “help me write code” to “help me manage complex engineering tasks.”
Dynamic Workflows aren’t meant to replace the ordinary way of using Claude Code — they give complex tasks stronger organization. For simple tasks, plain Claude Code is enough; for complex ones, especially those that need decomposition, parallelism, verification, and iterative progress, reach for Dynamic Workflows.
I’d recommend trying it against your own real work — the real value isn’t just understanding the feature, but finding the usage that fits your team’s and your own development flow. Source: https://claude.com/blog/a-harness-for-every-task-dynamic-workflows-in-claude-code
]]>Anthropic 最近发布了 Claude Code Dynamic Workflows：Claude Code 不再只是单个 agent 在一个上下文里干活，而是可以为当前任务临时写一套专属 harness——一个 JavaScript workflow，用来调度多个子 agent 协作。我读完原文又试了一下，最大的体会是：过去写进 prompt 里的那些”请仔细检查”“别漏测试”，正在变成结构化的执行流程。本文是一篇功能梳理 + 我自己的思考。原文：A harness for every task: Dynamic Workflows in Claude Code。
核心一句话：Claude Code 可以为任务即时生成自己的 harness。 它执行一个 JavaScript workflow，文件里有一组特殊函数，用来 spawn 并协调多个子 agent，而不是把所有事情塞进单一上下文窗口。
这些子 agent 可以有各自独立的上下文窗口和聚焦的目标，还可以指定各自使用的模型，甚至运行在各自独立的 worktree 中；workflow 本身就是普通 JavaScript（可以用 JSON、Math、Array 等），并支持中断后恢复。
原文给出六个典型编排模式：
传统 Claude Code 处理普通编码任务已经很强，但任务一复杂、链路一长，单上下文就开始吃力：信息全挤在一个窗口里，容易溢出或丢细节。在这个大背景下，原文明确点名了单上下文的三个失败模式：
Dynamic Workflows 的设计目标，就是用多个独立上下文和结构化流程把这几类问题压下去。
它更适合复杂、高价值、长链路的任务，而不是简单的代码改动。原文推荐的方向，加上我自己想到的场景：
一句话：只要一个任务需要拆解、并行、验证、合成，Dynamic Workflows 就有发挥空间。
我觉得最大的变化是：AI Coding 正在从 prompt 驱动，走向 workflow 驱动。
过去我们更多是在写 prompt——”请一步步检查”“请别漏测试”“请帮我 review”。这些其实是对着同一个上下文反复叮嘱。Dynamic Workflows 把这些要求变成更稳定的执行结构：先规划、再拆解、多 agent 并行执行、独立 agent 交叉验证、最后统一合成、不满足条件就继续循环。
这让 AI 更像一个可以临时组建的小型工程团队，而不是单个助手。
简单试用后，我的感受是 agent 内置的 harness 能力又上了一个台阶。
它最直接的价值是缓解复杂任务里的上下文窗口压力：不同子任务交给不同 agent、用各自独立的上下文完成，不需要把所有信息都挤在同一个窗口里。
更关键的是质量。让做这件事的上下文同时去给它打分，是不可靠的；换一个独立上下文来审查，才跳得出自我背书的偏向。 一个 agent 负责实现，另一个按 checklist 审查，第三个汇总结论——这正是 adversarial verification 模式的意义。
我觉得后续最值得探索的，是 Dynamic Workflows + Skills 的组合：把团队的常见流程沉淀成 skill——schema 变更检查、SQL review、migration checklist、release note、regression test、incident analysis、PR review rubric——再用 Dynamic Workflows 把这些 skill 串成一套更自动化、更可复用的工程流程。这可能是 AI 助手从”帮我写代码”进化到”帮我管理复杂工程任务”的关键一步。
Dynamic Workflows 不是要取代普通的 Claude Code 用法，而是为复杂任务提供更强的组织能力。简单任务，直接用 Claude Code 就够了；复杂任务，尤其是需要拆解、并行、验证、循环推进的任务，再考虑上 Dynamic Workflows。
推荐结合自己的真实工作场景实践一下——真正有价值的，不只是看懂这个功能，而是找到适合自己团队和个人开发流程的用法。原文：https://claude.com/blog/a-harness-for-every-task-dynamic-workflows-in-claude-code
]]>Ten years as a software engineer, and I’ve never met a technical shift that aimed straight at the profession itself the way agent coding does — and it all happened in the last three months. I recently read Augment’s “How we hire AI-native engineers now,” which redefines the human role as moving “from author to architect and editor.” The line that stung: pure coding ability is no longer the primary thing that differentiates engineering talent. This is my own reflection after reading it — not a retelling. The original is worth reading yourself.
Augment’s piece (by Alex Ding, Alyah Sablan, Chris Marty, and Vinay Perneti) opens with a blunt question: how do you hire engineers when agents write 99% of the code? Link at the bottom — I really recommend the original.
What stung was personal: the core capital I’ve built over ten years is exactly the thing getting commoditized — “writing code fast and correctly.” So my reflexive anxiety isn’t “I can’t write code anymore.” It’s the harder one — what’s left of my differentiation?
Underneath sit two things that were bundled together for a decade and are now splitting apart: being good at writing code, and being good at deciding what to write and steering a human-plus-agent system to the right outcome. Inside the phrase “he’s a good engineer,” those two always felt like one thing; only when code gets cheap do you see that one is depreciating and the other appreciating.
When the cost of producing code drops toward zero, the most expensive mistake becomes building the wrong thing — and your moat moves with it, from “how fast you write” to “how right you choose.”
The article has a “traditional vs AI-native engineering” table that I think is its sharpest part (paraphrasing their framework):
| Traditional | AI-native |
|---|---|
| Writing code | Specifying intent, evaluating tradeoffs |
| Implementing solutions | Orchestrating agents |
| Solving problems | Choosing the right problems |
| Individual output | System-level outcomes |
From there they derive six dimensions of AI-native engineering, each with a core question:
Notice what’s missing from the list: “pure coding ability” doesn’t appear as a standalone dimension. Not because it’s unimportant, but because it’s no longer the thing that separates one engineer from another. They also name four talent profiles (AI-native systems / product / applied-AI / early-professional engineers), each weighting the six dimensions differently — details in the original.
For a working engineer, the useful thing about reading someone’s hiring rubric is translating it into “where do I invest next.” Mine:
1. Move skill investment from “coding speed” to things that compound. Capital invested narrowly in “fast and correct” is now a depreciating asset; capital in judgment, product taste, agent orchestration, and learning velocity compounds. This isn’t a one-time tradeoff — it’s a revaluation of career capital, charged with interest, by the year.
2. “Agent leverage” is a delegation skill. The article has an analogy I like: using agents is like managing a report who’s astonishingly fast and occasionally, very confidently, wrong. Shaping a problem so it can execute well, pulling it back when it drifts, and verifying its output — that’s a different muscle from writing code.
3. Don’t declare “coding doesn’t matter” across the board. Where the hard part is the code — novel algorithms, performance-critical kernels, areas agents are still weak — raw coding ability remains a differentiator. Commoditization advances unevenly; this split hasn’t reached every corner.
I’m not pessimistic. This isn’t an “engineers are out of a job” story — it’s a “the craft is moving up the abstraction stack” story. Just as high-level languages once commoditized assembly skill and the value moved up a rung, agent coding is the next rung. What gets commoditized was never “the engineer” — it’s the most automatable layer of the engineer’s work.
Augment says it themselves: nobody has this fully figured out yet, but hiring is already changing whether the interview process has caught up or not. As a ten-year engineer still actively learning and adapting to the new tools, I’m sharing this in that spirit.
]]>Original (read it): How we hire AI-native engineers now — Augment Code
做了十年软件工程师，我从没遇到过哪次技术变革像现在的 agent coding 这样，直接冲着「职业」本身来——而且就发生在过去三个月内。最近读到 Augment 那篇《我们现在如何招聘 AI 原生工程师》，它把人的角色重新定义为「从作者转向架构师和编辑者」。它真正刺到我的是一句话：纯粹的编码能力，已经不再是区分工程人才的首要因素。这篇是我读完之后的个人思考——不是复述原文，原文值得你自己读。
Augment 这篇文章（作者 Alex Ding、Alyah Sablan、Chris Marty、Vinay Perneti）开篇就抛出一个问题：当 agent 写掉 99% 的代码，你该怎么招工程师？ 原文链接放在文末，强烈建议读原版。
我被刺到的点很私人：我这十年攒下的核心资本，恰好就是那个正在被商品化的东西——「写代码写得又快又对」。所以我下意识的焦虑，不是「我不会写代码了」，而是更难回答的那个——我的差异化到底还剩什么？
这背后是两件过去十年被捆在一起、现在正在分叉的事：擅长写代码，和擅长决定该写什么、并把人加 agent 这套系统 driving 到正确结果。在「他是个好工程师」这句话里，这两者一直感觉是一回事；只有当代码变得便宜，你才看出来——一个在贬值，一个在升值。
当写代码的成本趋零，最贵的错误就变成了「构建了错误的东西」——你的护城河也跟着从「写得多快」挪到了「选得多对」。
文章里有一张「传统工程 vs AI 原生工程」的对照表，我觉得是全文最锋利的部分（以下为我对原文框架的转述）：
| 传统工程 | AI 原生工程 |
|---|---|
| 编写代码 | 明确意图、评估权衡 |
| 实现解决方案 | 编排智能体 |
| 解决问题 | 选择正确的问题 |
| 个人产出 | 系统级结果 |
顺着这个方向，他们从第一性原理梳理出 AI 原生工程的六个维度，每个维度对应一个核心问题：
注意这张表里缺了什么：「纯粹编码能力」没有作为一个独立维度出现。 不是不重要，而是不再是把人和人区分开的那一项。他们还给出了四类人才画像（AI 原生系统 / 产品 / 应用 AI / 早期职业工程师），每类对这六维的权重不同——细节在原文里，这里不展开。
读别人的招聘标准，对一个在职工程师真正有用的，是把它翻译成「我接下来往哪投入」。我的三点：
1. 把技能投资从「编码速度」挪向会复利的地方。 窄投在「写得快、写得对」上的能力，现在是贬值资产；投在判断力、产品品味、agent 编排、学习速度上的能力会复利。这不是一次性的取舍，而是一笔按年计息的职业资本重估。
2. 「智能体杠杆」就是一种委派能力。 原文有个比喻我很喜欢：用 agent 像是管一个快得惊人、但偶尔会非常自信地出错的下属。把问题组织成它能高效执行的形状、在它偏航时拉回来、并验证它的产出——这和写代码是两套肌肉。
3. 别一刀切地宣布「编码不重要」。 在难点就在代码本身的地方——新算法、性能关键内核、agent 还很弱的领域——纯编码能力仍然是差异化因素。商品化是不均匀推进的，这道分叉还没烧到每个角落。
我不悲观。这不是「工程师要失业了」的故事，而是「这门手艺正在沿抽象层级往上挪」的故事——就像当年高级语言商品化了汇编技能，价值往上挪了一级，agent coding 不过是下一级台阶。被商品化的从来不是「工程师」，而是工程师工作里最容易被自动化的那一层。
Augment 自己也说了：目前还没有人把这件事完全想明白，但招聘已经在变，不管面试流程跟没跟上。作为一个还在积极学习、适应新工具的十年工程师，我把这篇分享出来，与君共勉。
]]>原文（强烈建议读原版）：How we hire AI-native engineers now — Augment Code