Claude How-To

中文

English
Tiếng Việt
Українська
日本語

中文

English
Tiếng Việt
Українська
日本語

Appearance

用户输入 ​

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 引用，而不是代码片段，以避免上下文过时。

4. 质量约束 ​

创建或更新 CLAUDE.md 时：

  1. 目标长度：少于 300 行，理想情况下少于 100 行
  2. 不要写风格规则：移除任何 lint/format 相关说明
  3. 不要写任务特定说明：移到单独文件中
  4. 不要写代码片段：改用文件引用
  5. 不要重复信息：不要重复 package.json 或 README 中已有内容

5. 必备章节 ​

一个结构良好的 CLAUDE.md 应包含：

markdown
# 项目名称

一句简短的项目描述。

## 技术栈
- 主语言和版本
- 关键框架/库
- 数据库/存储（如有）

## 项目结构
[仅适用于 monorepo 或复杂结构]
- `apps/` - 应用入口
- `packages/` - 共享库

## 开发命令
- 安装：`command`
- 测试：`command`
- 构建：`command`

## 关键约定
[只保留非显而易见、高影响的约定]
- 约定 1，简要说明
- 约定 2，简要说明

## 已知问题 / 坑点
[经常让开发者踩坑的内容]
- 问题 1
- 问题 2

6. 需要避免的反模式 ​

不要包含：

  • 代码风格指南（交给 lint 工具）
  • 如何使用 Claude 的说明
  • 对显而易见模式的冗长解释
  • 复制粘贴的代码示例
  • 泛泛而谈的最佳实践（例如“写干净的代码”）
  • 特定任务的说明
  • 自动生成内容
  • 大量 TODO 列表

7. 验证清单 ​

在最终确定前，检查：

  • 少于 300 行（最好少于 100 行）
  • 每一行都适用于所有会话
  • 没有风格/格式规则
  • 没有代码片段（使用文件引用）
  • 命令已经验证可用
  • 对复杂项目使用了渐进式披露
  • 已记录关键坑点
  • 没有与 README.md 重复

输出格式 ​

对于 create 或默认模式： ​

  1. 分析项目
  2. 按上述结构起草 CLAUDE.md
  3. 向用户展示草稿以供审阅
  4. 在获得批准后写入相应位置

对于 update： ​

  1. 读取现有 CLAUDE.md
  2. 按最佳实践进行审计
  3. 识别：
    • 需要删除的内容（风格规则、代码片段、任务特定内容）
    • 需要压缩的内容
    • 缺失的重要信息
  4. 向用户展示修改建议
  5. 在获得批准后应用修改

对于 audit： ​

  1. 读取现有 CLAUDE.md
  2. 生成报告，包括：
    • 当前行数与目标的对比
    • 可通用于所有会话内容的百分比
    • 发现的反模式列表
    • 改进建议
  3. 不要修改文件，只做报告

AGENTS.md 处理 ​

如果用户请求创建或更新 AGENTS.md：

从 v2.1.277 起，Claude Code 会直接把 AGENTS.md 作为项目指令读取。 但前提是工作目录以及它上面的每一级目录都没有 CLAUDE.md、.claude/CLAUDE.md 或 CLAUDE.local.md。~/.claude/CLAUDE.md、受管理的 CLAUDE.md 和 .claude/rules/ 不计入这项检查，它们仍会一并加载。该行为由 /config 中的 Project instructions 控制：claude-md-or-agents-md（默认）、claude-md-and-agents-md、claude-md、managed-only。在无法直接读取的环境中 — v2.1.277 之前的版本（在 Bedrock/Vertex/Foundry、LLM 网关或关闭遥测的情况下为 v2.1.281 之前），或升级后的第一个会话 — 退回到在 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 应该更聚焦