claude-md

name	claude-md
description	按照 AI 代理接入最佳实践创建或更新 CLAUDE.md 文件

用户输入

$ARGUMENTS

你必须先考虑用户输入再继续(如果不为空)。用户可以指定:

• create -- 从零创建新的 CLAUDE.md
• update -- 改进已有 CLAUDE.md
• audit -- 分析并报告当前 CLAUDE.md 的质量
• 特定路径(例如 src/api/CLAUDE.md 用于目录级指令)

核心原则

LLM 是无状态的:CLAUDE.md 是唯一在每个会话中自动加载的文件。它是 AI 代理接入你的代码库时的主要引导文档。

黄金法则

1. 少即是多:前沿 LLM 可以遵循约 150-200 条指令。Claude Code 的系统提示词本身已占用约 50 条。保持你的 CLAUDE.md 聚焦且精简。

2. 普适性原则:只包含与每次会话都相关的信息。任务特定的指令应放在单独的文件中。

3. 不要把 Claude 当作 Linter:风格规则会增加上下文负担并降低指令遵循度。应使用确定性工具(prettier、eslint 等)代替。

4. 永远不要自动生成:CLAUDE.md 是 AI 工具链中杠杆效应最高的地方。需经过深思熟虑手动精心编写。

执行流程

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/ 文件夹:

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 时:

1. 目标长度:300 行以内(理想情况下 100 行以内)
2. 不含样式规则:移除任何 lint/格式化指令
3. 不含任务特定指令:移至独立文件
4. 不含代码片段:改用文件引用
5. 不含冗余信息:不重复 package.json 或 README 中的内容

5. 必备章节

结构良好的 CLAUDE.md 应包含:

# 项目名称

一句话简要描述。

## 技术栈
- 主要语言及版本
- 关键框架/库
- 数据库/存储(如有)

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

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

## 关键约定
[仅限非显而易见的高影响约定]
- 约定 1 及简要说明
- 约定 2 及简要说明

## 已知问题 / 常见坑
[容易让开发者踩坑的事项]
- 问题 1
- 问题 2

6. 应避免的反模式

不要包含:

• 代码风格指南(使用 linter)
• 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. 生成报告,包含:
   • 当前行数 vs 目标行数
   • 普适性内容占比
   • 发现的反模式列表
   • 改进建议
3. 不修改文件,仅报告

AGENTS.md 处理

如果用户请求创建/更新 AGENTS.md:

AGENTS.md 用于定义专用代理的行为。与 CLAUDE.md(用于项目上下文)不同,AGENTS.md 定义:

• 自定义代理角色和能力
• 代理特定的指令和约束
• 多代理场景的工作流定义

应用相似的原则:

• 保持聚焦和精简
• 使用渐进披露
• 引用外部文档而非嵌入内容

注意事项

• 始终在纳入前验证命令可用
• 有疑虑就留在外面----少即是多
• 系统提示词会告诉 Claude CLAUDE.md "可能相关也可能无关"----噪音越多越容易被忽略
• Monorepo 最受益于清晰的 WHAT/WHY/HOW 结构
• 目录级 CLAUDE.md 文件应当更加聚焦