claude-md

## 用户输入 ```text $ARGUMENTS ``` 在继续之前，你**必须**先考虑用户输入（如果不为空）。用户可能会指定： - `create` - 从零创建新的 CLAUDE.md - `update` - 改进已有的 CLAUDE.md - `audit` - 分析并报告当前 CLAUDE.md 的质量 - 一个具体路径，用于创建或更新（例如 `src/api/CLAUDE.md` 代表目录级说明） ## 核心原则 **LLM 是无状态的**：CLAUDE.md 是每次对话中唯一会自动包含的文件。它是让 AI agent 了解代码库的主要入门文档。 ### 黄金法则 1. **少即是多**：前沿 LLM 大约能遵循 150-200 条指令。Claude Code 的系统提示词本身已经占了大约 50 条，因此 CLAUDE.md 必须聚焦且简洁。 2. **只放通用信息**：只包含每次会话都适用的内容。任务特定的说明应该放在单独文件里。 3. **不要把 Claude 当成 lint 工具**：风格指南会膨胀上下文并降低指令遵循效果。应改用确定性工具（如 prettier、eslint 等）。 4. **绝不自动生成**：CLAUDE.md 是 AI harness 中杠杆最高的位置。应该经过认真思考后手工编写。 ## 执行流程 ### 1. 项目分析 首先分析当前项目状态： 1. 检查是否存在已有的 CLAUDE.md 文件： - 根目录：`./CLAUDE.md` 或 `.claude/CLAUDE.md` - 目录级：`**/CLAUDE.md` - 全局用户配置：`~/.claude/CLAUDE.md` 2. 识别项目结构： - 技术栈（语言、框架） - 项目类型（monorepo、单体应用、库） - 开发工具（包管理器、构建系统、测试运行器） 3. 查看已有文档： - 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/` 文件夹： ```text agent_docs/ |- building_the_project.md |- running_tests.md |- code_conventions.md |- architecture_decisions.md ``` 在 CLAUDE.md 中引用这些文件，并写明： ```markdown 关于详细的构建说明，请参考 `agent_docs/building_the_project.md` ``` **重要**：使用 `file:line` 引用，而不是代码片段，以避免上下文过时。 ...