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 摘要：指出 Vibe Coding 短期易致缺陷与安全问题、长期堆积技术债；职业上，中位“翻译者”型编程会被挤压，具抽象能力或商业与独立开发能力者将受益，持续学习与上下文工程将决定竞争力。

[以下是方便搜索索引的大纲(AI 生成)，请读原文]
1. 术语澄清与立场：Vibe Coding vs Context Coding
• Vibe Coding 的原始内涵：忘记代码存在、全对话驱动、不看 diff、一次性项目可用但有趣而不严肃。
• 混用导致争论，应区分：Vibe Coding（对话式全托管）与 Context Coding（上下文驱动的 AI 辅助编程）。

2. Context Coding 的核心：上下文工程（Context Engineering）
• 除大语言模型（LLM）能力外，关键在于“如何给到合适的上下文”。
• Chat、RAG、Rules、MCP、文档接入等，实质都是提升上下文质量与可控性。

3. GitHub Copilot：从窗口上下文到补全范式
• 优点：将当前文件上下文提供给 LLM；基于注释的补全提升效率。
• 局限：模型能力与上下文长度受限、跨文件理解弱、早期无法直接编辑代码、需人工复制粘贴。

4. Cursor：从补全到“编程智能体”
• 能力叠加：专用 Tab 模型 + Claude 3.5 Sonnet，速度与质量同步提升，支持直接编辑。
• 上下文工程：对 codebase 做 RAG 索引，语义检索多文件上下文；@ 文件/目录、Git 历史、文档索引、Rules 保持风格一致性。
• 场景覆盖：跨文件调用、多文件修复、模块重构、功能新增。
• 商业取舍：次数/速率/模型自动降级等策略影响体验，存在波动。

5. Claude Code：命令行范式与“量大管饱”的上下文
• 全局分析：开场即扫描项目结构与技术栈，耗费 tokens 换来更贴合原项目规范的输出。
• 检索策略：采用 grep/find/git/cat 等 Unix 工具代替 RAG，更符合工程师的搜索路径。
• 争议对比：RAG 注重召回广覆盖但精度与时效可能不稳；grep 精度高匹配业务上下文但对话轮次与 tokens 消耗更多。
• 适配生态：天然契合 bash、MCP、CI/CD 与 DevOps 自动化的脚本化工作流。

6. 如何更好地进行 Context Coding（实践清单）
• 规则文件：提供技术栈、目录结构、命名约定与用途（.github/copilot-instructions.md、.rulers、CLAUDE.md；可用 Ruler 统一管理）。
• 上下文建模：常用脚本（install/lint/test/build）、工具类、核心模块/方法的清单与定位。
• 开发流程：需求拆分为子任务、记录进度、渐进式修改与小步提交、优先可读性与一致性、函数聚焦单一职责。
• 调试与知识更新：以日志替代 IDE 调试；用 MCP/context7 接入最新文档与浏览器/网络日志，降低训练数据过时风险。
• 风险提示：上下文不是越多越好；易变信息需及时维护，否则误导大于帮助。

7. 个人实践与取舍
• 严肃工程偏好 Tab 补全，由人控抽象与分层，效率更稳定。
• Claude Code 适合陌生代码库的全局理解与不熟技术栈任务。
• 工具中立：择善而用，不做工具信徒；LLM 正改变调试与一次性代码的工作习惯。

8. Vibe Coding 的风险与案例
• 风险画像：短期带来缺陷与安全漏洞，长期堆积技术债、可理解性与稳定性下降。
• 反面案例：Leo 使用 Cursor 全程 Vibe Coding，上线后遭攻击与越权，最终关停并复盘“生产环境不应部署不安全代码”。
• 正面机会：levelsio 以 100% AI + Cursor + Grok 3 做 MMO，17 天达 100 万美元 ARR；但其自身具接管能力与经验。
• 职业演进：LLM 蚕食“翻译者”型编程，中位岗位被压缩；顶尖工程师与具商业/营销能力的开发者将受益；独立与小团队更主流。

9. 结语与方法论走向
• LLM 能力与上下文工程相辅相成；上下文管理与可视化（如 /context）是关键产品力。
• 谁能提供“更好上下文 + 更好控制”，谁就更可能在 AI 编程时代胜出。

Guangzhengli

谈谈 AI 编程工具的进化与 Vibe Coding