AI Made Writing Code Easier. It Made Engineering Harder.

本文探讨了人工智能（AI）对软件工程行业的深远影响，提出了一个核心悖论：虽然 AI 显著降低了“写代码”的门槛，却让“做一名工程师”变得前所未有的困难。作者 Ivan Turkovic 指出，随着 AI 辅助工具和智能体的普及，代码生成的效率大幅提升，但这导致了行业基准线的无形移动。管理层往往认为 AI 减轻了负担，但现实是工程师的期望产出成倍增加，工作范围也从单纯的开发扩展到了产品思维、架构决策和复杂的系统维护。

文章引用了 2026 年《哈佛商业评论》的一项研究，显示 83% 的员工认为 AI 增加了工作量，初级员工的职业倦怠率远高于高管。这种现象源于“加速陷阱”：任务变快导致任务量增加，进而导致对 AI 的过度依赖，最终形成一个工作强度不断升级的循环。此外，工程师正面临身份危机，从“创造者”转变为“审查者”，而审查 AI 生成的代码往往比自己编写更耗时且缺乏上下文。

对于初级工程师而言，AI 吞噬了基础的练习任务，导致人才培养链条断裂。作者呼吁领导层应意识到这一转变的艰巨性，通过提供系统性培训、设定明确的角色边界、重新定义衡量指标以及保护初级人才管道来应对挑战。对于工程师个人，则建议在拥抱工具的同时，坚持掌握底层原理，并学会设定职业边界以避免倦怠。

本文探讨了在处理大型、成熟代码库时，如何通过将大语言模型（LLM）视为一种“性能较差的通用计算机”来提升 AI 代理（Agents）的工作效率。作者 Mario Zechner 指出，当前的“代理工程”往往缺乏工程严谨性，开发者通常只是向 AI 投喂信息并祈祷结果正确。在大型项目中，LLM 面临上下文缺失、缺乏审美（倾向于生成过度设计的代码）以及上下文降级（超过 100k token 后性能下降）等痛点。

为了解决这些问题，作者提出了一套方法论：提示词（Prompts）即代码，.json/.md 文件即状态。在这种模型下，“程序”是用自然语言编写的提示词，它定义了逻辑和控制流；“输入”是代码库文档和用户指令；“状态”则序列化存储在磁盘上的 JSON 或 Markdown 文件中，而非仅仅依赖不稳定的模型上下文。这种方式实现了工作流的可重现性和确定性。

文章以将 Spine 动画运行时从 Java 移植到 C++ 的真实案例展示了这一方法的威力。通过预先生成的 porting-plan.json 跟踪进度，并使用 port.md 作为执行脚本，作者引导 Claude Code 按照严格的步骤（查找待处理类型、打开相关文件、人工确认、执行移植、编译测试、更新状态）进行操作。这种结构化的方法将原本需要 2-3 周的人工移植工作缩短到了 2-3 天。作者强调，这种思维转变将 AI 辅助编程从一种随机的尝试转变为一种可控的工程学科。

Claude Code 是一个代理式（Agentic）编程环境，它超越了传统聊天机器人的范畴，能够自主读取文件、运行命令、修改代码并解决复杂问题。本文档核心观点认为，要发挥 Claude Code 的最大潜力，开发者需要从“自己写代码”转变为“描述需求并引导代理执行”。

文档强调，上下文窗口管理是使用中的核心约束。随着对话增长，Claude 的性能会因上下文填满而下降，导致遗忘指令或产生错误。因此，高效使用的关键在于：1. 提供验证手段：通过测试用例、截图或预期输出来让 Claude 自我校验，这是提高成功率的最强杠杆；2. 遵循科学工作流：采用“探索-计划-实施-提交”的四阶段模式，利用“计划模式（Plan Mode）”分离思考与执行；3. 精准的上下文注入：利用 @ 引用文件、粘贴图片或通过管道传输数据，减少模糊性。

在环境配置方面，文档详细介绍了 CLAUDE.md 的作用，它是跨会话持久化项目规范的关键。此外，通过配置权限、集成 CLI 工具（如 gh）、连接 MCP 服务器以及创建自定义技能（Skills）和子代理（Subagents），可以极大地扩展 Claude 的能力。最后，文档提出了规模化作业的思路，如非交互模式、并行会话和扇出式（Fan-out）任务分配，并总结了应避免的常见失败模式（如“大杂烩”会话和过度复杂的配置）。

随着 AI 智能体（Agents）能力的增强，开发者开始要求它们处理跨越数小时甚至数天的复杂任务。然而，让智能体在多个上下文窗口（Context Windows）中保持一致的进度仍是一个难题。核心挑战在于，长时运行的智能体必须以离散的“会话”形式工作，而每个新会话开始时都没有之前的记忆，就像一群轮班工作的工程师，每个人到岗时都不知道前一班发生了什么。

为了解决这一“失忆”问题，Anthropic 开发了一套双重方案，并集成在 Claude Agent SDK 中。该方案包含两个核心角色：初始化智能体（Initializer Agent）和编码智能体（Coding Agent）。初始化智能体负责在首次运行时搭建环境，包括创建功能列表（JSON 格式）、初始化 Git 仓库、编写环境启动脚本（init.sh）以及进度记录文件（claude-progress.txt）。编码智能体则负责在后续的每个会话中进行增量开发，确保每次只处理一个功能，并在结束时留下清晰的工件（Artifacts）供下一班次使用。

研究发现，智能体常见的失败模式包括：试图一次性完成所有工作（One-shotting）导致上下文耗尽、在功能未完成时过早宣布胜利、以及缺乏端到端测试。通过引入结构化的 JSON 功能清单、强制性的 Git 提交记录以及基于 Puppeteer 的浏览器自动化测试，Claude 能够更有效地识别 Bug 并保持代码库的整洁。这种方法不仅提高了开发效率，还确保了智能体在进入新会话时能通过运行 pwd、阅读日志和执行初始化脚本快速进入状态。尽管仍存在视觉识别局限等挑战，但这一框架为长时运行的 AI 协作提供了可行的工程路径。

本文探讨了人工智能（AI）对软件工程行业的深远影响，提出了一个核心悖论：虽然 AI 让“写代码”变得前所未有的简单，但却让“做工程师”变得更加困难和复杂。

作者指出，自 2023 年以来，软件工程师的产出基准线在无形中被大幅拉高。AI 工具缩短了编写代码的时间，但这并没有让工程师早点下班，反而导致了工作量的急剧扩张和职业倦怠。根据 2026 年的研究，超过 80% 的员工感到工作量增加，而管理层对此却缺乏共识。

这种转变引发了工程师的“身份危机”。许多人入行是因为热爱解决问题和编写代码的创造感，但现在他们正被迫转变为“代码审查员”，在永不停歇的自动化流水线上进行质量把控，失去了手工艺人的成就感。同时，工程师的职责范围也在剧烈扩张，他们现在需要兼顾产品思维、架构决策、安全评估和运维，这种“全栈化”往往演变成了无偿的职责蔓延。

此外，文章提出了“监督悖论”：审查 AI 生成的代码往往比自己亲手写代码更累，因为 AI 产出的代码缺乏决策背景和逻辑推导过程。对于初级工程师来说，AI 正在吞噬他们的“练手”机会，导致行业人才梯队面临断裂风险。

最后，作者呼吁领导层重新审视衡量标准，从关注产出速度转向关注系统稳定性、代码质量和团队健康；同时也建议工程师坚守技术基础，学会设定界限，并在新的职业版图中寻找机会。

本文介绍了 OpenAI 进行的一项为期五个月的工程实验：在“智能体优先”（Agent-first）的世界中，利用 Codex（基于 GPT-5）构建并交付了一款内部 Beta 软件产品，且未手动编写任何一行代码。该产品拥有数百万行代码，涵盖了应用逻辑、测试、CI 配置、文档及监控工具，开发效率提升了约 10 倍。

实验的核心结论是：在智能体时代，工程师的角色发生了根本性转变。人类不再是代码的编写者，而是环境的设计者、意图的指定者和反馈循环的构建者。团队通过“人类引导，智能体执行”的模式，实现了平均每人每天 3.5 个 PR 的高产出。为了让智能体高效工作，团队采取了一系列创新措施：首先，提高应用的“可读性”，通过集成 Chrome DevTools 和本地观测栈（Logs/Metrics），让智能体能自主调试 UI 和性能；其次，将代码库（Repository）作为唯一的知识来源，通过结构化的文档和 AGENTS.md 索引，解决上下文稀缺和规则陈旧的问题；最后，通过极其严格的架构分层和自定义 Linter 强制执行“工程品味”，防止架构漂移。

此外，实验还揭示了高吞吐量下的新挑战，如“AI 废料”（AI slop）的堆积。团队通过引入“黄金原则”和自动化的“垃圾回收”机制（即定期运行重构智能体）来保持代码库的健康。这种模式证明了，只要拥有正确的脚手架和反馈系统，智能体可以实现从发现 Bug 到修复、验证并合并 PR 的全自动化闭环。

Peter Steinberger 在本文中分享了他截至 2025 年 8 月的最优 AI 开发工作流。其核心理念是“少即是多”（Less is More），强调通过极简的工具链实现最高生产力。他目前的工作流已从完全依赖 VS Code 转向以 Ghostty 终端 + Claude Code (CLI) 为核心的模式。

在硬件方面，他推崇戴尔 UltraSharp U4025QW 40 英寸显示器，其超宽分辨率允许同时显示 4 个 Claude 实例和浏览器，无需频繁切换窗口。在软件工具上，他放弃了不稳定的 VS Code 内置终端，转而使用 Ghostty。虽然他仍保留 VS Code 用于代码查看，并使用 Cursor 或 GPT-5 进行代码审查，但主要的编码和重构工作由 Claude Code 承担。

Peter 强调了“上下文管理”的重要性。他通过在状态栏显示会话 ID、使用 CLAUDE.md 记录环境配置、以及坚持在同一上下文中编写测试来优化 AI 的表现。他认为，虽然 AI 代理（Agents）非常强大，但人类的实时引导（Steering）至关重要，以防止 AI 偏离方向。此外，他倾向于使用具有强大 CLI 支持的服务（如 Vercel、psql、gh），因为这能让 AI 代理更高效地执行任务。尽管 Claude 的费率限制可能带来挑战，但他认为目前没有更好的替代方案，这种工作流极大地提升了他的开发效率。

本文由 Peter Steinberger 撰写，探讨了在 2025 年底，随着 AI 模型（特别是 GPT-5.2 和 Codex）的进化，软件开发范式发生的剧变。作者提出了“以推理速度交付”（Shipping at Inference-Speed）的概念，认为现在的开发瓶颈已不再是编写代码，而是 AI 的推理时间和人类的深度思考。

文章详细对比了 OpenAI 的 Codex 与 Anthropic 的 Claude (Opus) 在实际工程中的表现。作者指出，Codex 虽然在响应速度上可能较慢，但其在编写代码前会进行长时间的全局阅读和深度思考，从而在处理大型重构和复杂功能时具有更高的“一次性成功率”。作者分享了其高度自动化的工作流：不再依赖传统的 IDE（如 Xcode），而是通过 CLI 和 Agent 直接驱动开发；不再编写详尽的 Prompt，而是通过简短指令、截图和跨项目参考来引导 AI。

此外，作者介绍了其开发的工具（如 oracle、VibeTunnel、Clawdis），展示了 AI 如何全方位接管从系统底层转换到智能家居控制的各项任务。他强调，现代开发者的核心竞争力在于选择技术栈、设计系统架构以及与 AI 协作的直觉。最后，作者分享了其 Codex 配置文件，为追求极致开发效率的工程师提供了实践参考。

本文由 Manus 的开发者 Yichao 'Peak' Ji 撰写，分享了在构建 AI Agent（智能体）过程中关于“上下文工程”（Context Engineering）的核心经验。作者指出，相比于耗时且难以迭代的端到端模型微调，Manus 选择基于前沿模型的上下文学习能力进行构建，通过优化上下文结构来实现快速迭代。

文章总结了六大核心原则：

1. 围绕 KV-Cache 设计：KV-Cache 命中率是生产环境的关键指标，直接影响延迟和成本。开发者应保持 Prompt 前缀稳定、采用“仅追加”模式并明确缓存断点。
2. 掩码而非删除：面对庞大的工具库，不应动态删除工具（这会破坏缓存并导致模型困惑），而应通过 Logit 掩码（Masking）在解码阶段限制动作空间。
3. 将文件系统视为上下文：针对长上下文导致的性能下降和高成本，Manus 将文件系统作为外部持久化存储，让模型按需读写，实现可恢复的上下文压缩。
4. 通过“背诵”操纵注意力：利用如 todo.md 的任务列表，让模型在长任务中不断重申目标，防止注意力漂移。
5. 保留错误记录：不要清理失败的尝试，错误记录是模型学习和自我修正的关键证据。
6. 避免过度 Few-shot：过多的同质化示例会导致模型陷入行为模式的死循环，应引入结构化变体以增强鲁棒性。

作者强调，上下文工程是定义 Agent 行为、效率和扩展能力的关键，是构建智能体未来的基石。

本文是 Stripe 内部 AI 编码智能体“Minions”系列的第二部分，深入探讨了支撑这些智能体高效运行的底层架构与技术细节。Minions 是一种无需人工干预、端到端的单次编码智能体，每周在 Stripe 产生的合并 PR 超过 1300 个。

其核心优势在于充分复用了 Stripe 为人类工程师构建的成熟基础设施。首先，Minions 运行在名为 devbox 的云开发环境中，这种环境具备并行化、可预测和隔离的特性，确保智能体在 10 秒内即可获得干净且配置齐全的工作空间。其次，Stripe 引入了 “蓝图”（Blueprints） 概念，这是一种结合了确定性代码节点和灵活性智能体节点的混合工作流，既保证了代码规范（如 Lint 检查）的强制执行，又保留了 LLM 处理复杂任务的能力。

在上下文获取方面，Minions 利用 规则文件（Rule files） 自动学习代码库规范，并通过集中的 Toolshed（基于 MCP 协议） 动态调用内部工具。最后，Minions 遵循“反馈左移”原则，在推送到 CI 之前进行本地自动化迭代，并限制 CI 循环次数以平衡成本与效率。Stripe 的经验表明，多年来在提升人类开发者效率上的投入，正成为 AI 智能体发展的巨大红利。

本文探讨了在 AI Agent 开发中，开发者是否真的需要模型上下文协议（MCP）。作者 Mario Zechner 指出，虽然 MCP 备受关注，但许多流行的 MCP 服务器（如 Playwright 或 Chrome DevTools MCP）过于臃肿，动辄占用数万个 Token（约占 Claude 上下文的 7%-9%），且难以扩展和组合。

作者提出了一种更简单、高效的替代方案：拥抱 Bash 脚本和原生代码。通过编写极简的 Node.js 脚本（利用 Puppeteer Core）并配合一份仅约 200 Token 的 README 说明，Agent 就能实现浏览器自动化、网页截图、执行 JS 和交互式元素选择等功能。这种方法的优势在于：1. 极高的 Token 效率，利用了模型已有的编程知识；2. 强大的组合性，脚本输出可直接存入文件或通过管道传输；3. 极易扩展，开发者可以随时让 AI 为自己编写新的工具脚本。

作者通过构建一套“浏览器工具集”展示了这一理念，包括启动浏览器、导航、执行 JS、截图、交互式选取元素（Pick Tool）以及获取 Cookie。最后，作者分享了如何通过设置环境变量和别名，在不同的 Agent（如 Claude Code）中复用这些工具，并呼吁开发者跳出 MCP 的框架，回归简单、灵活的开发模式。

本文详细记录了作者 Mitchell Hashimoto 采纳 AI 工具的六个阶段。起初，作者对 AI 持怀疑态度，认为聊天机器人（如 ChatGPT）在复杂编程任务中效率低下。随后，他通过“强制复现自身工作”的极端练习，掌握了使用 AI Agent（智能体） 的技巧，学会了如何拆解任务和提供验证手段。

随着探索深入，作者开发出了“日终代理”模式，利用非工作时间让 AI 进行调研和琐事处理；并进一步演进到“外包稳赢任务”阶段，在自己处理核心难题时，让 AI 在后台异步处理简单确定的任务。为了提升 AI 的准确率，他提出了“框架工程（Harness Engineering）”的概念，通过编写 AGENTS.md 约束文件和专用工具来防止 AI 重犯错误。目前，作者的目标是维持一个“始终有 Agent 在运行”的工作流，将 AI 视为一个虽不完美但极具生产力的“机器人伙伴”。作者强调，这并非为了追逐热度，而是作为一名软件工匠在探索提升效率的新边界。

Eli Mernit 在文中提出了一个创新的架构理念：将公司或个人生活建模为一个“文件系统”（Filesystem），并以此作为 AI 代理（Agent）的核心运行环境。他以 Openclaw 为例，展示了当 AI 能够直接访问和操作本地文件系统时，其能力将得到质的飞跃。在这种模式下，文件系统不仅是存储介质，更是“状态”本身。无论是个人邮件、睡眠数据，还是公司的案件、账单和合同，都被统一表示为文件。

这种架构解决了当前企业 AI 落地的一大痛点：数据孤岛。目前企业数据分散在各种 SaaS 平台（如 QuickBooks, Outlook, SharePoint 等），缺乏统一的命名空间。如果将公司还原为一组文件夹，AI 代理（如以 Claude 为编排器）就能通过简单的“读写文件”来处理复杂的业务逻辑。此外，Unix 风格的文件权限管理可以自然地映射到公司的组织架构和治理结构中。作者认为，AI 代理的本质可以简化为：文件系统作为状态，大模型作为编排器。

Almost every line of code in vinext was written by AI. But here's the thing that matters more: every line passes the same quality gates you'd expect from human-written code. The project has 1,700+ Vitest tests, 380 Playwright E2E tests, full TypeScript type checking via tsgo, and linting via oxlint. Continuous integration runs all of it on every pull request. Establishing a set of good guardrails is critical to making AI productive in a codebase.

The process started with a plan. I spent a couple of hours going back and forth with Claude in OpenCode to define the architecture: what to build, in what order, which abstractions to use. That plan became the north star.

Cloudflare 推出了一项名为 vinext 的实验性项目，旨在解决 Next.js 在非 Node.js 环境（如 Cloudflare Workers）中部署困难且笨重的问题。vinext 并非 Next.js 的包装器，而是基于 Vite 重新实现的 Next.js API 兼容层。该项目由一名工程师在 AI（Claude）的辅助下，仅用一周时间、花费约 1,100 美元 Token 成本完成。

vinext 实现了 Next.js 16 约 94% 的 API 覆盖率，包括 App Router、Pages Router、RSC（React Server Components）和 Server Actions。初步基准测试显示，vinext 的构建速度比 Next.js 快达 4.4 倍，客户端包体积缩小了 57%。此外，vinext 引入了创新的“流量感知预渲染”（TPR）技术，通过分析实际流量仅预渲染高频访问页面，解决了大规模站点构建缓慢的问题。目前该项目处于实验阶段，已在 CIO.gov 等生产环境中进行初步应用。

Paul Graham 在文中指出，审美趣味并非不可捉摸的个人偏好，而是一套客观存在的、跨学科的优秀设计原则。他认为，如果审美是完全主观的，那么创作者就无法通过学习和练习来提升自己的水平。通过观察数学、绘画、工程、软件和建筑等领域，他总结出了一系列优秀设计的共同特征：简洁、永恒、解决正确的问题、具有启发性、看似容易、利用对称性、模仿自然、不断迭代、敢于挑战常规等。

Graham 强调，优秀的设计往往诞生于人才聚集的“中心地带”（如 15 世纪的佛罗伦萨），因为环境对个人能力的激发至关重要。他鼓励创作者培养对“丑陋”和“拙劣”的敏锐嗅觉，因为伟大的作品往往源于对现状的不满和对更优解决方案的执着追求。最终，他将伟大作品的秘诀归结为：极其严苛的审美趣味，加上实现这种审美目标的能力。

Stripe 开发了名为 Minions 的内部原生编程智能体（Coding Agents），旨在实现“一键式”（one-shot）且完全无人值守的端到端编程任务。目前，Stripe 每周有超过 1,000 个合并的拉取请求（PR）完全由 Minions 生成。虽然这些代码仍需人工审核，但代码本身不含任何人工编写的内容。

Minions 的核心价值在于通过并行化处理任务来节省开发者宝贵的注意力资源。它们通常从 Slack 消息或内部工单系统启动，自动在隔离的开发环境（devbox）中运行，完成代码编写、运行 Lint 检查、通过 CI 测试，并最终提交 PR。

Stripe 选择自研而非直接使用市面上的通用工具，是因为其代码库规模庞大（数亿行）、技术栈独特（Ruby + Sorbet）且业务风险极高（年处理交易额超 1 万亿美元）。Minions 深度集成了 Stripe 的内部开发工具链，利用 MCP（模型上下文协议）访问内部文档和 400 多个工具。通过“左移”反馈机制，Minions 能够在本地环境和 CI 阶段自动修复错误，确保交付高质量的代码。Minions 的成功标志着编程智能体已从实验阶段进入到大规模生产实践。

本文由 Jesse Vincent 撰写，介绍了他在 2025 年 10 月开发的名为 “Superpowers” 的 Claude Code 插件系统。该系统旨在通过“技能（Skills）”机制系统化地增强 AI 编码代理的能力。Superpowers 的核心理念是将复杂的开发流程（如头脑风暴、计划、实施、TDD 测试）转化为 AI 可检索和遵循的 Markdown 文档（SKILL.md）。

作者详细说明了 Superpowers 的工作流：它不仅能自动管理 Git worktree 以支持并行任务，还能在实施阶段调用子代理进行代码编写和审查。文章重点探讨了“技能”的本质——它们是 AI 的指令集，可以通过阅读书籍、分析历史对话或自我总结来不断进化。此外，作者还分享了如何利用心理学中的“说服原则”对 AI 进行压力测试，以确保其在紧急或高压场景下仍能严格遵守既定技能。目前，该项目已作为 Claude 插件发布，未来计划加入技能共享机制和基于 SQLite 的长期记忆系统，使 AI 能够检索过去的对话记录以辅助当前任务。

这是一篇关于 AI 智能体工程（Agentic Engineering）实战经验的深度分享。作者 Peter Steinberger 详细介绍了他在处理 30 万行代码的大型项目时，如何通过“直接对话”而非复杂的工程套路，实现 AI 编写 100% 代码的高效工作流。

本文核心观点是：回归简单，直接与 AI 对话（Just Talk To It）。作者认为，当前的 AI 智能体工程中存在过多的“花招”（如复杂的子代理、RAG、计划模式等），这些往往会降低效率。作者目前已全面转向使用 gpt-5-codex 命令行工具（CLI），并总结了一套实战经验：

1. 工具选择：相比于 Claude Code，作者更推崇 OpenAI 的 codex。它在上下文容量（230k）、Token 使用效率、消息队列功能、运行速度以及沟通语言的“情绪价值”上表现更优。
2. 核心策略：引入“爆炸半径”（Blast Radius）概念，主张通过多个并行运行的代理处理小规模、原子化的任务，而不是一个庞大且难以控制的任务。
3. 提示词技巧：随着模型能力的提升，提示词应变得更短、更直接。作者强调了“截图”在提供上下文方面的巨大威力，并建议通过 tmux 管理后台任务，而非依赖复杂的插件系统。
4. 维护与重构：AI 编写的代码并非完美，作者投入 20% 的时间进行“代码除草”（重构），利用 knip、eslint 等工具保持代码库健康。
5. 工程本质：尽管 AI 承担了编码工作，但架构设计、系统思考和用户体验仍需人类把关。管理 AI 代理的能力正逐渐演变为高级软件工程师的核心竞争力。

Cloudflare 推出了基于 Code Mode（代码模式） 的全新模型上下文协议（MCP）服务器，旨在解决 AI 智能体（Agent）在调用外部工具时面临的“上下文窗口压力”问题。传统的 MCP 服务器通过为每个 API 接口定义独立工具来工作，这在面对拥有数千个端点的复杂 API（如 Cloudflare API）时，会迅速耗尽模型的上下文配额。

Code Mode 的核心思想是**“以代码代替描述”**：不再向模型展示成百上千个工具定义，而是仅提供 search()（搜索）和 execute()（执行）两个核心工具。模型通过编写 JavaScript 代码来检索 OpenAPI 规范并执行复杂的 API 调用链。这种方式将 Cloudflare 全量 API 的上下文占用从 117 万个 token 骤降至约 1,000 个，降幅达 99.9%。

安全性方面，所有生成的代码均在 Cloudflare 的 Dynamic Worker 隔离沙箱中运行，确保了环境安全与隐私。此外，Cloudflare 还开源了 Code Mode SDK，允许开发者在自己的 MCP 服务器中应用此技术。未来，Cloudflare 计划通过 MCP Server Portals 将此模式扩展到多服务集成场景，实现跨平台的统一、低成本智能体交互。

Writing a good CLAUDE.md

本文深入探讨了如何为 AI 编码助手（如 Claude Code、Cursor 等）编写高质量的 CLAUDE.md（或其开源等价物 AGENTS.md）配置文件。核心观点在于，大语言模型（LLM）本质上是无状态的，它们在每次对话开始时对代码库一无所知，而 CLAUDE.md 是唯一会被默认注入到每一次对话中的文件。因此，该文件承担着“入职培训”的关键角色，必须清晰地告知 AI 项目的背景（WHAT）、目的（WHY）以及协作方式（HOW）。

文章强调了“少即是多”的原则。研究表明，前沿 LLM 只能稳定遵循约 150-200 条指令，且随着指令增加，遵循质量会统一下降。为了防止 Claude 忽略指令，CLAUDE.md 应保持精简（建议少于 300 行，甚至少于 60 行），且内容必须具有普适性。

为了解决复杂项目信息量大的问题，作者提出了“渐进式披露”策略，即在 CLAUDE.md 中仅保留核心框架和指向其他详细文档（如测试指南、架构说明）的指针，让 AI 根据任务需要自行读取。此外，文章警告不要将 CLAUDE.md 用作代码检查工具（Linter），而应利用确定性的自动化工具处理格式问题。最后，作者指出 CLAUDE.md 是整个工作流中杠杆率最高的部分，绝不应依赖自动生成，而需开发者精心打磨，以确保 AI 输出的高质量。