authoring-claude-md

CLAUDE.md 和规则编写

创建有效的 CLAUDE.md 文件和 .claude/rules/ 规则文件，作为 AI 编码 Agent 的项目专属记忆。

目的

CLAUDE.md 文件和规则文件可为 AI Agent 提供：

• 不明显的约定、架构模式和注意事项
• 对反复出现问题的已验证解决方案
• 标准文档中未提及的项目专属背景信息
• 仅在涉及相关文件时加载的路径范围指令

不适用于：显而易见的模式、重复文档内容或通用编码建议。

核心原则

• 突出重点，减少噪声：每句话都必须提供不明显的价值。如果 AI Agent 阅读代码库就能推断出来，请省略。
• 提供可执行的背景信息：重点说明“该怎么做”以及“为什么重要”，而非描述现有内容。
• 解决实际阻碍，而非理论上的顾虑：根据实际遇到的问题向 CLAUDE.md 添加内容，而不是假设可能出现的情况。如果你反复向 Claude 解释同一件事，就把它写下来。如果还没遇到问题，就不要提前解决。

结构

使用标题来清晰组织内容。常见章节包括：架构、约定、注意事项、测试。使用 2–4 个章节，只纳入有价值的内容。

何时改用 .claude/rules/

对于较大的项目，可将指令拆分到 .claude/rules/ 下的多个文件中。每个 .md 文件涵盖一个主题。出现以下情况时，优先使用规则，而不是单个 CLAUDE.md：

• 指令超过 200 行
• 代码库不同部分适用不同规则（前端与后端、API 与 CLI）
• 多名团队成员分别维护不同章节
• 某些指令仅在处理特定文件类型时适用

规则文件基础

your-project/
├── .claude/
│   ├── CLAUDE.md           # Main project instructions
│   └── rules/
│       ├── code-style.md   # Always loaded
│       ├── testing.md      # Always loaded
│       └── security.md     # Always loaded

系统会递归发现文件，因此 frontend/ 和 backend/ 等子目录也可使用。不带 paths frontmatter 的规则会在启动时加载，其优先级与 .claude/CLAUDE.md 相同。

规则文件同样遵循这些编写原则：突出重点，减少噪声；提供可执行的背景信息；不包含显而易见的信息。

路径专属规则

使用包含 paths 字段的 YAML frontmatter，将规则限定到特定文件。这些规则仅在 Claude 读取与 glob 模式匹配的文件时加载，从而减少噪声并节省上下文。

---
paths:
  - "src/api/**/*.ts"
---

# API Development Rules

- All API endpoints must include input validation
- Use the standard error response format
- Include OpenAPI documentation comments

不带 paths 字段的规则会无条件生效。路径范围规则在读取文件时触发，而非每次使用工具时触发。

用户级规则

适用于所有项目的个人规则存放在 ~/.claude/rules/。这些规则会先于项目规则加载，因此项目规则具有更高优先级。

~/.claude/rules/
├── preferences.md    # Personal coding preferences
└── workflows.md      # Preferred workflows

规则与技能

规则会在每个会话中加载（或在打开匹配的文件时加载）。对于不需要持续提供上下文的特定任务指令，请改用技能。技能仅在被调用或 Claude 判断其相关时加载。

应包含的内容

架构决策：为何选择微服务而非单体架构、事件驱动模式、状态管理

不明显的约定：

• “对于 linter 无法识别的私有 API，使用 _internal 后缀”
• “日期字段始终使用 UTC，格式化在客户端进行”
• “报表应避免使用 ORM，在 /queries 中使用原始 SQL”

反复出现的问题：

• “身份验证中的 TypeError：确保 verify() 使用 Buffer.from(secret, 'base64')”
• “缓存竞争条件：检查状态前先获取锁”

项目模式：错误处理、日志记录、API 版本控制、迁移

应排除的内容

• 行号：文件会变更，引用也会失效。请使用描述性路径：“在 src/auth/middleware.ts 中”，而不是“第 42 行”
• 显而易见的信息：“我们使用 React”（可在 package.json 中查看）。大模型会从代码库探索中学习上下文中的模式。
• 代码风格指南：格式规则、命名约定或由代码检查工具强制执行的模式。请使用 ESLint、Prettier、Black、golangci-lint 或类似工具，以及 Claude Code Hooks 来运行格式化工具。
• 通用建议：“编写好的测试”对项目没有具体价值。
• 设置步骤：应放在 README 中，除非有高度非标准的情况。
• 重复内容：如果内容已在 README 或现有文档中，请链接到相关内容，而不是重复说明。
• 特定任务的细节：数据库架构、API 规范、部署流程应放在各自的文档中。请链接到这些文档，而不是重复内容。
• 临时备注：TODO、一次性错误修复和临时变通方法应放在代码注释中。
• 冗长的描述：条目应简洁，删去冗长的解释。
• 大杂烩式条目：不是每个注意事项都适合放在这里。请问自己：“这对大多数编码会话都相关吗？”如果不相关，就应放在代码注释或具体文档中。
• 过度强调格式：不要把每句话或每个要点的开头都加粗，仅在确有必要警示时使用强调格式。

冲突审查

添加内容前，请检查它与其他已加载内容是否冲突：用户级 ~/.claude/CLAUDE.md、同级规则文件，以及涵盖相同内容的技能。相互冲突的指令（例如“酌情编写文档”与“绝不添加注释”并存）会迫使 Agent 在开始工作前解决矛盾，而且每次解决方式可能不同。

每个主题只放在一处：

• 已在其他地方说明：保留在原处，不要重复
• 比现有规则范围更窄：将其写成明确说明覆盖范围的例外（“整个代码库使用 Prettier；/legacy 保留现有格式”）
• 确实与用户级或全局规则冲突：请告知用户，不要悄悄覆盖

路径范围规则用于细化根目录的 CLAUDE.md 中适用于对应文件的规则；不应与其相反。

链接到现有文档

请链接到现有文档，而不是重复其中的内容。说明何时应阅读这些文档：

好：

# Architecture
Event-driven architecture using AWS EventBridge.

- For database schema: see src/database/SCHEMA.md when working with data models
- For auth flows: see src/auth/README.md when working with authentication

不好：将架构表格、部署步骤或 API 流程复制到 CLAUDE.md 中

写作风格

具体明确：

• 不好：“使用身份验证系统时要小心”
• 好：“身份验证令牌 1 小时后过期。后台任务必须使用 src/auth/refresh.ts 中的 refreshToken() 刷新令牌”

简洁明了：

• 不好：“需要注意的是，使用数据库层时，应当了解……”
• 好：“数据库查询：使用 Prisma 处理 CRUD，在 /queries 中使用原始 SQL 编写复杂报表”

使用主动语态：

• 不好：“应在部署前运行迁移”
• 好：“部署前运行迁移：npm run migrate:prod”

何时更新

在以下情况下添加内容到 CLAUDE.md：

• 通过代码库探索或解决复杂问题后，发现了不明显的模式
• 解决了一个经过大量调查的问题，其他 Agent 以后也会遇到
• 发现了无法从代码中立即看出的注意事项

不要添加《应排除的内容》中列出的内容（一次性修复、临时变通方法、文档中已有的信息、冗长的解释）。

拼写规范

始终使用澳大利亚英语拼写

示例结构

# Architecture
Event-driven architecture using AWS EventBridge. Services communicate via events, not direct calls.

Auth: JWT tokens with refresh mechanism. See src/auth/README.md for detailed flows when working on authentication.
Database schema and relationships: see src/database/SCHEMA.md when working with data models.

# Conventions
- API routes: Plural nouns (`/users`, `/orders`), no verbs in paths
- Error codes: 4-digit format `ERRR-1001`, defined in src/errors/codes.ts
- Feature flags: Check in middleware, not in business logic
- Dates: Always UTC in database, format client-side via src/utils/dates.ts
- Documentation: Use DocBlocks for public functions, never use "smart" formatting markdown

# Gotchas

**Cache race conditions**: Always acquire lock before checking cache status

**Background job authentication**: Tokens expire after 1 hour. Refresh using
`refreshToken()` in src/auth/refresh.ts before making API calls.

# Testing

- Tests should never have external API calls or dependencies.
- Run `make test` before committing.

Token Budget

CLAUDE.md 建议控制在 1k-4k 个 Token。大多数项目的内容在 100-300 行。对于大多数项目，单个 CLAUDE.md 就够了；如果超出预算，可考虑拆分到 .claude/rules/ 文件中（尤其是某些内容仅适用于特定文件类型时）。如果超出预算：

1. 改写得更简洁
2. 删除通用建议
3. 确保没有重复内容

使用 wc -c CLAUDE.md 估算字符数，再将字符数除以约 4，得出 Token 数量。

Review Checklist

定稿前：

• 确认没有混入「应排除的内容」（行号、代码风格、重复的文档、临时备注、冗长的指导）
• 措辞简洁，没有重复
• 各章节仅补充不明显的价值
• 格式简单，不使用智能引号、长破折号或过多粗体
• 信息不太可能很快过时
• 优先使用带替代方案的正向规则（「使用分号或句号分隔分句」），而非单纯的禁令（「永远不要使用长破折号」）
• 聚焦于稳定、长期适用的模式
• 内容紧凑、简洁且可执行，不冗长，也不以叙述为主