# Claude Md

按最佳实践创建或更新 CLAUDE.md 文件，以便为 AI agent 提供最优的项目入门上下文

- Repository: https://github.com/luongnv89/claude-howto (46363 stars)
- Category: AI and agents
- License: MIT
- Last updated: 2026-10-29
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add luongnv89/claude-howto --skill claude-md -g -a claude-code -y`
Codex: `npx skills add luongnv89/claude-howto --skill claude-md -g -a codex -y`
Cursor: `npx skills add luongnv89/claude-howto --skill claude-md -g -a cursor -y`
Gemini CLI: `npx skills add luongnv89/claude-howto --skill claude-md -g -a gemini-cli -y`

## Description

按最佳实践创建或更新 CLAUDE.md 文件，以便为 AI agent 提供最优的项目入门上下文

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

## 用户输入

```text
$ARGUMENTS
```

在继续之前，你**必须**先考虑用户输入（如果不为空）。用户可能会指定：
- `create` - 从零创建新的 CLAUDE.md
- `update` - 改进已有的 CLAUDE.md
- `audit` - 分析并报告当前 CLAUDE.md 的质量
- 一个具体路径，用于创建或更新（例如 `src/api/CLAUDE.md` 代表目录级说明）

## 核心原则

**LLM 是无状态的**：CLAUDE.md 是每次对话都会加载的主要项目文件（与自动记忆和未限定作用域的 rules 一起加载）。它是让 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. **目标长度**：少于 200 行
2. **不要写风格规则**：移除任何 lint/format 相关说明
3. **不要写任务特定说明**：移到单独文件中
4. **不要写代码片段**：改用文件引用
5. **不要重复信息**：不要重复 package.json 或 README 中已有内容

### 5. 必备章节

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

```markdown
# 项目名称

一句简短的项目描述。

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

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

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

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

The rest: https://github.com/luongnv89/claude-howto/blob/HEAD/zh/03-skills/claude-md/SKILL.md