Hacker News 中文摘要

文章摘要

文章指出，由于LLM模型（如Claude）是无状态的，每次会话开始时对代码库一无所知，因此需要通过CLAUDE.md文件在每次会话中向其传递关键信息。该文件应包含技术栈、代码结构等核心内容，帮助模型快速理解代码库。

文章总结

如何编写高质量的CLAUDE.md文件

核心原则：LLM本质上是无状态的

大型语言模型(LLM)是静态函数，其权重在推理时是固定的。这意味着： 1. 每次会话开始时，编码助手对代码库一无所知 2. 需要主动告知与当前任务相关的代码库信息 3. CLAUDE.md是实现这一目标的最佳方式

CLAUDE.md的核心作用

这个文件应该包含三个关键维度： - 项目构成：技术栈、项目结构、代码库地图（特别是monorepo中的共享包和应用） - 项目目的：解释各组成部分的功能和存在意义 - 工作方式：包括构建工具选择(bun/node)、测试方法等

常见误区与解决方案

内容被忽略问题：
- Claude会评估内容相关性，非普适性指令容易被忽略
- 解决方案：确保内容具有广泛适用性
编写原则：
- 指令精简：前沿LLM最多能稳定遵循150-200条指令
- 文件长度：建议控制在300行以内（理想情况60行左右）
- 渐进披露：将特定任务说明放在独立文件中，通过引用方式引入
工具选择：
- 避免用LLM做格式化工作（应使用专业linter）
- 可配置Stop钩子或Slash Command来处理格式问题

最佳实践建议

不要自动生成CLAUDE.md文件，因其影响每个工作环节
采用"指针优于拷贝"原则，通过file:line引用保持信息更新
组织建议结构： agent_docs/ |- building_the_project.md |- running_tests.md |- code_conventions.md

关键结论

保持内容简洁普适
采用渐进式信息披露
区分LLM和linter的职责
手动精心设计这个高杠杆率的文件

通过遵循这些原则，可以显著提升与编码助手的协作效率。

评论总结

以下是评论内容的总结：

1. 关于Claude.md文件的讨论

支持使用Claude.md的观点
- 认为通过自动化检查（如linting、单元测试）和更新文档来替代Claude.md更有效：
"set up effective automated checks... and tell Claude to always run these before completing a task" (andersco)
"ensure docs on the codebase are up to date... update the docs for each new task" (andersco)
- 建议分目录存放多个AGENTS.md文件以提高针对性：
"break out more specific AGENTS.md files in the subdirectories" (prettyblocks)

反对过度依赖Claude.md的观点
- 认为代码本身的文档（如README.md）已足够，无需额外文件：
"Just write what this file is supposed to do in a clear concise way... write README.md files" (pdp)
- 质疑其必要性，认为未来可能过时：
"None of this should be necessary... most of this advice will probably age like milk" (candiddevmike)

2. 关于模型性能与指令遵循的讨论

对模型能力的观察
- 指出模型在指令遵循上的局限性，并赞赏相关数据的量化分析：
"the ability to follow long lists of rules is one of the most obvious ways that virtually all AI models fail today" (johnfn)
"the graph is truly fantastic... I’ve never seen someone systematically measure it before" (johnfn)
- 建议扩展测试更多新模型（如Gemini 3、Claude 4.5等）：
"Curious... why they chose those models. How well does ChatGPT 5/5.1... Gemini 3... do?" (jasonjmcghee)

实际使用体验
- 部分用户认为模型进步显著，无需复杂配置：
"About 12 to 6 months ago this was not the case... the models have improved a lot" (serial_dev)
- 也有用户认为复杂场景下减少上下文干扰更有效：
"The more context you give the lower it’s upper end of quality becomes" (johnsmith1840)

3. 关于工作流程的建议

结构化方法
- 推荐分层引用文档的“目录式”管理：
"the Table-of-Contents approach... keep the context window streamlined" (vunderba)
"include a list of these files with a brief description" (vunderba引用文章)

简化交互
- 主张直接与模型对话，如同与同事协作：
"I simply highlight the relevant code... talk to these tools as if they were my colleagues" (serial_dev)
- 认为过度配置不如手动编码高效：
"if setting up all the AI infrastructure... takes this effort, I might as well code it myself" (gonzalohm)

4. 其他技术建议

调试工具需求：
"I’d be eager to read a tutorial about [logging proxy]" (eric-burel)
个性化提示词技巧：
"Have the agent address you as something specific... Rationality gives a great language for constraining the agent" (ctoth)

争议性观点

对优化方法的讽刺：
"Here’s how to use the slop machine better is such a ridiculous pretense" (acedTrex)

（注：所有评论均无评分数据，故未涉及认可度分析。）

撰写优质Claude.md指南 -- Writing a Good Claude.md