89e89d4aa3
Add Chinese (Simplified) translations for all documentation, organized under a dedicated zh/ directory that mirrors the English folder structure. Co-authored-by: tanqingkuang <tanqingkuang@users.noreply.github.com> Translations originally contributed by @tanqingkuang in #45. Restructured from *-CN.md suffix pattern into zh/ directory to prevent the EPUB builder (scripts/build_epub.py collect_folder_files) from picking up Chinese files via glob("*.md") inside module folders.
213 lines
5.8 KiB
Markdown
213 lines
5.8 KiB
Markdown
---
|
||
name: claude-md
|
||
description: 按最佳实践创建或更新 CLAUDE.md 文件，以便为 AI agent 提供最优的项目入门上下文
|
||
---
|
||
|
||
## 用户输入
|
||
|
||
```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：
|
||
|
||
AGENTS.md 用于定义专门的 agent 行为。与 CLAUDE.md（项目上下文）不同，AGENTS.md 定义的是：
|
||
- 自定义 agent 角色和能力
|
||
- agent 级约束与说明
|
||
- 多 agent 场景下的工作流定义
|
||
|
||
同样适用以下原则：
|
||
- 保持聚焦和简洁
|
||
- 使用渐进式披露
|
||
- 用外部文档引用代替内联内容
|
||
|
||
## 备注
|
||
|
||
- 在写入前始终验证命令是否可用
|
||
- 不确定时就不要写，少即是多
|
||
- 系统提醒会告诉 Claude，CLAUDE.md “可能相关，也可能不相关” - 噪音越多，越容易被忽略
|
||
- monorepo 最需要清晰的 WHAT/WHY/HOW 结构
|
||
- 目录级 CLAUDE.md 应该更聚焦
|