claude-md

name claude-md description 按最佳实践创建或更新 CLAUDE.md 文件，以便为 AI agent 提供最优的项目入门上下文 用户输入 $ARGUMENTS 在继续之前，你 必须 先考虑用户输入（如果不为空）。用户可能会指定： create - 从零创建新的 CLAUDE.md update - 改进已有的 CLAUDE.md audit - 分析并报告当前 CLAUDE.md 的质量 一个具体路径，用于创建或更新（例如 src/api/CLAUDE.md 代表目录级说明） 核心原则 LLM 是无状态的 ：CLAUDE.md 是每次对话中唯一会自动包含的文件。它是让 AI agent 了解代码库的主要入门文档。 黄金法则 少即是多 ：前沿 LLM 大约能遵循 150-200 条指令。Claude Code 的系统提示词本身已经占了大约 50 条，因此 CLAUDE.md 必须聚焦且简洁。 只放通用信息 ：只包含每次会话都适用的内容。任务特定的说明应该放在单独文件里。 不要把 Claude 当成 lint 工具 ：风格指南会膨胀上下文并降低指令遵循效果。应改用确定性工具（如 prettier、eslint 等）。 绝不自动生成 ：CLAUDE.md 是 AI harness 中杠杆最高的位置。应该经过认真思考后手工编写。 执行流程 1. 项目分析 首先分析当前项目状态： 检查是否存在已有的 CLAUDE.md 文件： 根目录： ./CLAUDE.md 或 .claude/CLAUDE.md 目录级： **/CLAUDE.md 全局用户配置： ~/.claude/CLAUDE.md 识别项目结构： 技术栈（语言、框架） 项目类型（monorepo、单体应用、库） 开发工具（包管理器、构建系统、测试运行器） 查看已有文档： README.md CONTRIBUTING.md package.json、pyproject.toml、Cargo.toml 等 2. 内容策略（WHAT, WHY, HOW） 围绕三个维度组织 CLAUDE.md： WHAT - 技术与结构 技术栈概览 项目组织方式（对 monorepo 尤其重要） 关键目录及其用途 WHY - 目的与背景 项目是做什么的 为什么做出这些架构决策 每个主要组件负责什么 HOW - 工作流与约定 开发流程（bun vs node、pip vs uv 等） 测试流程和命令 验证与构建方法 关键“坑点”或非显而易见的要求 3. 渐进式披露策略 对于较大的项目，建议创建 agent_docs/ 文件夹： agent_docs/ |- building_the_project.md |- running_tests.md |- code_conventions.md |- architecture_decisions.md 在 CLAUDE.md 中引用这些文件，并写明： 关于详细的构建说明，请参考 `agent_docs/building_the_project.md` 重要 ：使用 file:line 引用，而不是代码片段，以避免上下文过时。 4. 质量约束 创建或更新 CLAUDE.md 时： 目标长度 ：少于 300 行，理想情况下少于 100 行 不要写风格规则 ：移除任何 lint/format 相关说明 不要写任务特定说明 ：移到单独文件中 不要写代码片段 ：改用文件引用 不要重复信息 ：不要重复 package.json 或 README 中已有内容 5. 必备章节 一个结构良好的 CLAUDE.md 应包含： # 项目名称 一句简短的项目描述。 ## 技术栈 - 主语言和版本 - 关键框架/库 - 数据库/存储（如有） ## 项目结构 [仅适用于 monorepo 或复杂结构] - `apps/` - 应用入口 - `packages/` - 共享库 ## 开发命令 - 安装： `command` - 测试： `command` - 构建： `command` ## 关键约定 [只保留非显而易见、高影响的约定] - 约定 1，简要说明 - 约定 2，简要说明 ## 已知问题 / 坑点 [经常让开发者踩坑的内容] - 问题 1 - 问题 2 6. 需要避免的反模式 不要包含： 代码风格指南（交给 lint 工具） 如何使用 Claude 的说明 对显而易见模式的冗长解释 复制粘贴的代码示例 泛泛而谈的最佳实践（例如“写干净的代码”） 特定任务的说明 自动生成内容 大量 TODO 列表 7. 验证清单 在最终确定前，检查： 少于 300 行（最好少于 100 行） 每一行都适用于所有会话 没有风格/格式规则 没有代码片段（使用文件引用） 命令已经验证可用 对复杂项目使用了渐进式披露 已记录关键坑点 没有与 README.md 重复 输出格式 对于 create 或默认模式： 分析项目 按上述结构起草 CLAUDE.md 向用户展示草稿以供审阅 在获得批准后写入相应位置 对于 update ： 读取现有 CLAUDE.md 按最佳实践进行审计 识别： 需要删除的内容（风格规则、代码片段、任务特定内容） 需要压缩的内容 缺失的重要信息 向用户展示修改建议 在获得批准后应用修改 对于 audit ： 读取现有 CLAUDE.md 生成报告，包括： 当前行数与目标的对比 可通用于所有会话内容的百分比 发现的反模式列表 改进建议 不要修改文件，只做报告 AGENTS.md 处理 如果用户请求创建或更新 AGENTS.md： Claude Code 不会直接读取 AGENTS.md。 要让它生效，需要在 CLAUDE.md 中用 @AGENTS.md 导入，或者把 CLAUDE.md 软链接到它。这是关于这个文件最常见的误解。 AGENTS.md 是一个跨工具的项目上下文文件 — 和 CLAUDE.md 属于同一 类 文档，而不是 agent 定义格式。它的存在是为了让多个编码 agent 共用同一套项目约定： 构建、测试和 lint 命令 代码风格与架构约定 仓库结构以及各部分所在位置 Subagents 是单独定义的，放在 .claude/agents/*.md 里 — 不在 AGENTS.md 中。 同样适用以下原则： 保持聚焦和简洁 使用渐进式披露 用外部文档引用代替内联内容 备注 在写入前始终验证命令是否可用 不确定时就不要写，少即是多 系统提醒会告诉 Claude，CLAUDE.md “可能相关，也可能不相关” - 噪音越多，越容易被忽略 monorepo 最需要清晰的 WHAT/WHY/HOW 结构 目录级 CLAUDE.md 应该更聚焦