AI 摘要：本文介绍了如何编写一个高质量的 CLAUDE.md （或AGENTS.md）文件，以帮助大型语言模型如 Claude 在每次会话中准确理解项目上下文。作者强调 Claude 是无状态（stateless）的，需要通过 CLAUDE.md 主动引导项目背景和结构。文中指出主文件应聚焦通用信息、减少冗余指令、避免让模型充当代码检查工具，并提出了“渐进揭示(Progressive Disclosure)”原则来管理上下文信息。结论是：精简、聚焦、人工精心编写的 CLAUDE.md 才能真正成为助力开发的高杠杆点。

1. LLM 基础与 CLAUDE.md 的角色
• 强调 LLM 是无状态的，推理时并不会记忆过往对话。
• CLAUDE.md 文件是让模型理解代码库的唯一常驻入口，每次对话都会自动加载。
• 它的作用类似于为 Claude 提供项目结构图与工作指南。

2. CLAUDE.md 的内容原则：WHAT / WHY / HOW
• WHAT：介绍项目栈、架构与子模块结构，是 Claude 的“路线图”。
• WHY：说明项目目标与各部分用途，帮助 Claude 理解设计动机。
• HOW：告诉 Claude 如何执行任务，如构建流程、测试方式、工具链（例如使用 bun 还是 node）。
• 提醒不要塞入所有命令，应保持“够用、通用、可解释”。

3. Claude 忽略 CLAUDE.md 的原因及机制
• Claude 会根据系统提醒(<system-reminder>)判断上下文是否相关。
• 若文件含过多不相关信息，Claude 会选择性忽略。
• 这种机制是为防止用户使用 CLAUDE.md 添加无关“热修复”指令所设计。

4. 编写高质量 CLAUDE.md 的建议
• 遵循 context engineering best practices。
• 少即是多 (Less is more)：避免过多指令或与代码无关的规则。
• 研究表明 LLM 对 150–200 条指令的响应最为稳定，超过会急剧下降。
• Claude Code 的系统提示占掉约 50 条指令空间，因此应控制在极简范围内。

5. 文件长度与通用性建议
• 上下文窗口应专注于高相关的内容，而非填充冗余背景。
• 建议文件 <300 行，理想情况下 <60 行。
• 仅包含“通用适用”的指令与信息。

6. 渐进揭示 (Progressive Disclosure) 原则
• 将不同任务的指令拆分为独立的 Markdown 文件（如 agent_docs/ 目录）。
• 在主文件中只列出这些文件及简要说明，让 Claude 按需访问。
• 避免代码复制，推荐使用 file:line 引用；引用比拷贝更可维护。

7. Claude 不是代码检查工具
• 不应让 Claude 替代 linter 或 formatter。
• 代码风格应由确定性工具（如 Biome）自动处理。
• 可使用 Stop hook 或 Slash Command 将检查与格式化过程外挂给 Claude 参考，而非直接放入主文档中。

8. 避免自动生成或使用 /init
• 自动生成的文件通常内容冗余或缺乏针对性。
• CLAUDE.md 是高杠杆点，一旦草率配置，会对所有阶段输出产生负面连锁影响。
• 建议人工精雕细琢每一行指令，使其精准可靠。

9. 结论与最佳实践总结
• 明确项目的 WHY / WHAT / HOW。
• 内容简洁、普适、避免多余。
• 采用渐进式信息揭示策略。
• 使用独立工具执行语法或格式检查任务。
• 谨慎维护 CLAUDE.md——它影响整个代理（agent）表现的核心。

www.humanlayer.dev

Writing a good CLAUDE.md

`CLAUDE.md` is a high-leverage configuration point for Claude Code. Learning how to write a good `CLAUDE.md` (or `AGENTS.md`) is a key skill for agent-enabled software engineering.

AI 摘要：作者在 Filestage 的前端项目中使用 AI Agents（特别是 Claude Code）与 AST（Abstract Syntax Tree）技术，将近千个测试文件、六千多条测试从 React Testing Library v13 迁移至 v14。文章展示了从制定迁移指南、分步提交 PR、编写 codemod、自动化验证到改进 AI 提示的完整过程，最后总结出 AI 在大规模代码迁移中的优势与局限，并强调“小步迭代 + 自动化验证”的工程基本功仍然至关重要。

1. 项目背景与动机
• 公司使用旧版 React Testing Library 编写了 970 个测试文件，总计 6000 多测试用例。
• 升级至 v14 后 API 完全异步化，行为变化大，手动迁移代价极高。
• 作者决定尝试用 AI 辅助完成大规模迁移。

2. 准备与迁移指南
• 首次直接用 Claude Code CLI 自动迁移失败，暴露出测试失败过多、AI 调试混乱的问题。
• 于是转而使用 Claude Web 模式制作详细的迁移指南，分析版本差异与新 API。
• 确定主要变化：异步 API、测试 setup 模式更新、时序逻辑差异需人工介入。

3. 拆分改动与依赖并行安装
• 利用 NPM 的包别名功能同时运行 v13 与 v14，避免一次性大变更。
• 生成迁移指南并提交第一份 PR，保证团队迭代可控。

4. 编写与测试 codemod 自动化工具
• 使用 jscodeshift 解析代码为 AST，再生成批量修改工具。
• 编写输入输出测试用例以验证 codemod 效果（例如导入路径、 renderWithUserEvent 封装替换）。
• 自动测试 codemod 确保修改一致性和可验证性。

5. 实际迁移与 AI 协作循环
• 通过详细 prompt 指令让 Claude Code 分批迁移 10 个测试文件，执行 lint 检查与单测验证。
• 持续观察失败案例，不断改进 codemod 与迁移指南。
• 迁移指南从最初 4500 字扩充到 7500 字；codemod 从 271 行发展到近千行，测试覆盖更完备。
• 共执行 50 次迁移，形成 50 个独立 PR。

6. AI 性能与局限分析
• Claude Code 在调试测试与识别重复模式方面表现优异。
• 局限包括 context 深度不足、长任务遗忘指令、无法稳定维持覆盖率。
• 通过增加 JSON 格式的覆盖率报告输入，AI 能理解覆盖问题并修复。
• 网络波动与服务超限导致中断，验证仍需人工把关。

7. 工程启示与最终成果
• 整体用一周完成迁移，每个 PR 约半小时。
• 若纯人工迁移，估计需数月。
• 迁移过程机械但 AI 显著提升效率。
• 保持验证自动化、关注 edge case、理解底层工具机制，是让 AI 发挥价值的关键。
• 作者展望未来 AI 将进一步解放开发者，从“重复劳动”转向更有创造力的工作。

Eliocapella

Migrating 6000 React tests using AI Agents and ASTs

How I used AI to migrate 970 test files with 6000+ test cases from React Testing Library v13 to v14 in one week, through 50 PRs that would have taken months manually.

/plugin marketplace add anthropics/claude-code

/plugin install frontend-design@claude-code-plugins

Thariq(@trq212):Opus 4.5 is our best model yet for design & vision.
Here are some of my favorite UIs we made with Claude Code's frontend-design plugin.
To try this yourself add our marketplace in Claude Code:
/plugin marketplace add anthropics/claude-code
and then install the plugin:
/plugin install frontend-design@claude-code-plugins

yousa (@y0usali): 我把前几天在Trae的分享整理成了文字稿
「https://yousali.com/posts/20251124-how-to-coding-with-ai/」
这篇文章写给已经在或准备在真实生产项目里用 AI Coding 的后端 / 全栈工程师和技术管理者。
它不会教你「按钮在哪里」「哪个 prompt 最神」，而是想在大约 15 分钟里，帮你搞清楚三件事：
哪些任务交给 AI 最「划算」；
怎么让项目本身变得更「AI 友好」，提高一次命中率；
当生成不再是瓶颈时，工程师应该如何设计验证流程，把时间花在真正值钱的地方。

AI 摘要：作者总结三年 AI 编程经验，指出 AI 写代码的时代关键不在「准不准」而在「值不值」。文章从个人与团队两个视角分析了 AI 生成代码的最佳使用场景（高重复、低风险、易验证）、如何构建「AI 友好」项目，以及工程师心态从「写代码」到「验代码」的转变。核心结论是：生成已不再是瓶颈，验证才是新的核心；AI 的上限取决于给它的上下文（Context）。标准化与自动化是让 AI 值得信赖的关键，而工程师应成为定义任务与设计验证系统的「总工程师」。

1. 两种声音与早期弯路 —— 从试验到思考
• AI 编程存在两极化认知：「神迹」与「玩具」并存。
• 初期盲目尝试，成功靠运气，暴露问题在于目标定义不清。
• 结论：关键在于明确「让 AI 干什么」，而非讨论「准不准」。

2. 从关注准确率到计算性价比 —— 「甜点区」的发现
• 引入「效率增益」公式衡量 AI 协作的价值。
• 四类高性价比任务：高重复、高耗时、低风险、易验证。
• 案例：模块化模板 + few-shot 示例提升生成质量。
• 心态转变：接受 AI 错误，注重系统级可靠性。
• 工程协作比喻：把 AI 当成「聪明但不熟悉项目的实习生」。

3. 团队视角的优化 —— 让项目更「AI 友好」
• 数据显示企业中 20%–30% 新代码由 AI 生成，但效率提升有限。
• 关键差异在于：项目是否标准化与自动化。
• 标准化**：统一接口规范、术语表、文档说明，让人机共享上下文。
• 自动化：降低验证成本，AI 助力 pre-commit、自动测试、CI/CD 等流程。
• 实践公式：讲清规则 → AI 辅助执行 → 人专注高价值审查。

4. 工程师的心理负担与注意力管理
• 高频切换任务使「注意力成本」爆炸，人类像「上下文很小的 LLM」。
• 心流（flow）被碎片化交互打断，导致疲惫与效率下降。
• 自救方法：时间分层、AI 时分复用、三分钟原则、沟通卫生与单线专注。
• 重点转移：保护注意力等于提升系统整体吞吐。

5. 稳定的两条工程原则
• 原则一：生成已非瓶颈，验证是核心
• 聚焦测试、监控、回滚机制。考核应基于 Bug Lead Time 而非代码量。
• 原则二：上下文为王（Context is King）
• 上下文完整度决定 AI 产出质量。
• 推广路径：统一规范 → 写进仓库 → 自动化验证。
• 单句箴言：AI 写代码的水平 = 你提供上下文的水平。

6. 给三类读者的建议
• 新手：从小型任务切入，先找「值不值」感受。
• 重度用户：从优化上下文与验证流程入手。
• 管理者：亲自尝试，引导从「个人提速」走向「团队工程化」。

AI 摘要：本文作者作为 Claude Code 的深度用户，详细介绍了自己从 Cursor 转向全程使用 Claude Code 的开发体验，总结出一系列高效实用的使用建议。文章覆盖了 Claude Code 的 VS Code 插件启动、终端界面、权限系统、GitHub 集成、大型代码库表现、经济性、队列系统、自定义扩展、可视化界面及团队协作等方面，旨在帮助开发者最大化 Claude Code 在日常工作中的价值与便捷性。

Builder.io

How I use Claude Code (+ my best tips)

I switched from Cursor's agents to Claude Code weeks ago and I'm not going back. Here's how I use it and my best practical tips