Back to Details

authoring-claude-md

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

CLAUDE.md Authoring

CLAUDE.md 编写指南

Create effective CLAUDE.md files that serve as project-specific memory for AI coding agents.
创建有效的CLAUDE.md文件，作为AI编码Agent的项目专属记忆库。

Purpose

用途

CLAUDE.md files provide AI agents with:
  • Non-obvious conventions, architectural patterns and gotchas
  • Confirmed solutions to recurring issues
  • Project-specific context not found in standard documentation
Not for: Obvious patterns, duplicating documentation, or generic coding advice.
CLAUDE.md文件为AI Agent提供：
  • 不易察觉的约定、架构模式和常见陷阱
  • 针对反复出现问题的已验证解决方案
  • 标准文档中未涵盖的项目特定上下文信息
不适用于：显而易见的模式、重复文档内容或通用编码建议。

Core Principles

核心原则

Signal over noise: Every sentence must add non-obvious value. If an AI agent could infer it from reading the codebase, omit it.
Actionable context: Focus on "what to do" and "why it matters", not descriptions of what exists.
Solve real friction, not theoretical concerns: Add to CLAUDE.md based on actual problems encountered, not hypothetical scenarios. If you repeatedly explain the same thing to Claude, document it. If you haven't hit the problem yet, don't pre-emptively solve it.
重信号，去冗余：每一句话都必须提供非显而易见的价值。如果AI Agent通过阅读代码库就能推断出来，就不要写进去。
可落地的上下文：聚焦于“该做什么”和“为什么重要”，而非描述现有内容。
解决实际痛点，而非假想问题：基于实际遇到的问题添加内容，而非假想场景。如果你反复向Claude解释同一件事，就把它记录下来。如果还没遇到该问题，不要提前编写解决方案。

Structure

结构

Use XML-style tags for organisation. Common sections:
xml
<ARCHITECTURE>  System design, key patterns, data flow
<CONVENTIONS>   Project-specific patterns, naming
<GOTCHAS>       Non-obvious issues and solutions to recurring problems
<TESTING>       Test organisation, special requirements
Use 2-4 sections. Only include what adds value.
使用XML风格的标签进行组织。常见章节：
xml
<ARCHITECTURE>  系统设计、关键模式、数据流
<CONVENTIONS>   项目特定模式、命名规则
<GOTCHAS>       不易察觉的问题及常见问题的解决方案
<TESTING>       测试组织、特殊要求
使用2-4个章节，仅保留有价值的内容。

What to Include

应包含的内容

Architectural decisions: Why microservices over monolith, event-driven patterns, state management
Non-obvious conventions:
  • "Use 
    _internal
    suffix for private APIs not caught by linter"
  • "Date fields always UTC, formatting happens client-side"
  • "Avoid ORM for reports, use raw SQL in 
    /queries
    "
Recurring issues:
  • "TypeError in auth: ensure 
    verify()
    uses Buffer.from(secret, 'base64')"
  • "Cache race condition: acquire lock before checking status"
Project patterns: Error handling, logging, API versioning, migrations
架构决策：为何选择微服务而非单体架构、事件驱动模式、状态管理方案
不易察觉的约定：
  • "为未被代码检查工具捕获的私有API添加
    _internal
    后缀"
  • "日期字段始终使用UTC格式，格式化操作在客户端完成"
  • "报表功能避免使用ORM，在
    /queries
    目录中使用原生SQL"
反复出现的问题：
  • "认证模块中的TypeError：确保
    verify()
    方法使用Buffer.from(secret, 'base64')"
  • "缓存竞态条件：检查状态前需获取锁"
项目模式：错误处理、日志记录、API版本控制、迁移策略

What to Exclude

应排除的内容

  • Line numbers: Files change, references break. Use descriptive paths: "in 
    src/auth/middleware.ts
    " not "line 42"
  • Obvious information: "We use React" (visible in package.json)
  • Setup steps: Belongs in README unless highly non-standard
  • Generic advice: "Write good tests" adds no project-specific value
  • Temporary notes: "TODO: refactor this" belongs in code comments
  • Duplicate content: If it's in README, don't repeat it
  • 行号：文件会变更，行号引用会失效。使用描述性路径：比如“在
    src/auth/middleware.ts
    中”而非“第42行”
  • 显而易见的信息："我们使用React"（在package.json中可见）
  • 安装步骤：属于README的内容，除非是高度非标准的步骤
  • 通用建议："编写优质测试"不具备项目特定价值
  • 临时注释："TODO: 重构此处"应放在代码注释中
  • 重复内容：如果已在README中存在，请勿重复

Anti-Patterns

反模式

Code style guidelines: Don't document formatting rules, naming conventions, or code patterns that linters enforce. Use ESLint, Prettier, Black, golangci-lint, or similar tools. LLMs are in-context learners and will pick up patterns from codebase exploration. Configure Claude Code Hooks to run formatters if needed.
Task-specific minutiae: Database schemas, API specifications, deployment procedures belong in their own documentation. Link to them from CLAUDE.md rather than duplicating content.
Kitchen sink approach: Not every gotcha needs CLAUDE.md. Ask: "Is this relevant across most coding sessions?" If no, it belongs in code comments or specific documentation files.
代码风格指南：不要记录格式化规则、命名约定或代码检查工具已能强制执行的代码模式。使用ESLint、Prettier、Black、golangci-lint等工具。大语言模型（LLM）具备上下文学习能力，会从代码库探索中获取模式。如有需要，配置Claude Code Hooks来运行格式化工具。
任务细节：数据库schema、API规范、部署流程应放在各自的文档中。在CLAUDE.md中链接至这些文档，而非重复内容。
堆砌内容：并非所有常见陷阱都需要写入CLAUDE.md。请自问：“这在大多数编码会话中都相关吗？”如果不是，应放在代码注释或特定文档中。

Linking to Existing Documentation

链接至现有文档

Point to existing docs rather than duplicating content. Provide context about when to read them:
Good:
xml
<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
</ARCHITECTURE>
Bad: Copying schema tables, pasting deployment steps, or duplicating API flows into CLAUDE.md
Use 
file:line
references for specific code: "See error handling in src/utils/errors.ts:45-67"
指向现有文档而非重复内容。同时说明何时需要阅读这些文档：
示例（正确）：
xml
<ARCHITECTURE>
采用AWS EventBridge的事件驱动架构。

- 数据库schema：处理数据模型时请查看src/database/SCHEMA.md
- 认证流程：处理认证相关工作时请查看src/auth/README.md
</ARCHITECTURE>
示例（错误）：将schema表、部署步骤或API流程复制粘贴到CLAUDE.md中
针对特定代码使用
file:line
格式引用：“错误处理示例请查看src/utils/errors.ts:45-67”

Writing Style

写作风格

Be specific:
  • ❌ "Use caution with the authentication system"
  • ✅ "Auth tokens expire after 1 hour. Background jobs must refresh tokens using 
    refreshToken()
    in 
    src/auth/refresh.ts
    "
Be concise:
  • ❌ "It's important to note that when working with our database layer, you should be aware that..."
  • ✅ "Database queries: Use Prisma for CRUD, raw SQL for complex reports in 
    /queries
    "
Use active voice:
  • ❌ "Migrations should be run before deployment"
  • ✅ "Run migrations before deployment: 
    npm run migrate:prod
    "
表述具体：
  • ❌ “使用认证系统时请谨慎”
  • ✅ “认证令牌1小时后过期。后台任务必须使用
    src/auth/refresh.ts
    中的
    refreshToken()
    方法刷新令牌”
简洁明了：
  • ❌ “需要注意的是，在处理数据库层时，你应该知晓...”
  • ✅ “数据库查询：CRUD操作使用Prisma，复杂报表在
    /queries
    目录中使用原生SQL”
使用主动语态：
  • ❌ “迁移应在部署前运行”
  • ✅ “部署前运行迁移：
    npm run migrate:prod
    ”

When to Update

更新时机

Add to CLAUDE.md when:
  • Discovering a non-obvious pattern discovered after codebase exploration
  • Solving an issue that took significant investigation that will be encountered again by other agents
  • Finding a gotcha that's not immediately clear from code
Don't add:
  • One-off fixes for specific bugs
  • Information easily found in existing docs
  • Temporary workarounds (these belong in code comments)
  • Verbose descriptions or explanations
在以下场景下更新CLAUDE.md：
  • 探索代码库后发现不易察觉的模式
  • 解决了需要大量调研且其他Agent可能再次遇到的问题
  • 发现仅通过代码无法立即察觉的陷阱
请勿在以下场景更新：
  • 针对特定bug的一次性修复
  • 可在现有文档中轻松找到的信息
  • 临时变通方案（应放在代码注释中）
  • 模糊或过于冗长的说明

Spelling Conventions

拼写约定

Always use Australian English spelling
始终使用澳大利亚英语拼写

Example Structure

示例结构

xml
<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.
</ARCHITECTURE>

<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
</CONVENTIONS>

<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.
</GOTCHAS>

<TESTING>
Run `make test` before committing. Integration tests require Docker.
</TESTING>
xml
<ARCHITECTURE>
采用AWS EventBridge的事件驱动架构。服务通过事件通信，而非直接调用。

认证：带刷新机制的JWT令牌。处理认证相关工作时请查看src/auth/README.md获取详细流程。
数据库schema及关联关系：处理数据模型时请查看src/database/SCHEMA.md。
</ARCHITECTURE>

<CONVENTIONS>
- API路由：使用复数名词（`/users`、`/orders`），路径中不包含动词
- 错误码：4位格式`ERRR-1001`，定义在src/errors/codes.ts中
- 功能开关：在中间件中检查，而非业务逻辑中
- 日期：数据库中始终使用UTC格式，通过src/utils/dates.ts在客户端完成格式化
</CONVENTIONS>

<GOTCHAS>
**缓存竞态条件**：检查缓存状态前必须获取锁

**后台任务认证**：令牌1小时后过期。调用API前请使用`src/auth/refresh.ts`中的`refreshToken()`方法刷新令牌。
</GOTCHAS>

<TESTING>
提交前运行`make test`。集成测试需要Docker环境。
</TESTING>

Token Budget

Token 预算

Aim for 1k-4k tokens for CLAUDE.md. Most projects fit in 100-300 lines. If exceeding:
  1. Reword to be more concise
  2. Remove generic advice
  3. Ensure there's no duplicated content
Check token count: 
ingest CLAUDE.md
(if available)
CLAUDE.md的内容目标控制在1k-4k Token。大多数项目的内容长度在100-300行左右。如果超出预算：
  1. 改写内容，使其更简洁
  2. 删除通用建议
  3. 确保没有重复内容
检查Token数量：使用
ingest CLAUDE.md
（若可用）

Review Checklist

审核清单

Before finalising:
  • Wording is concise and not duplicated
  • Sections only add non-obvious value
  • No code style guidelines (use linters instead)
  • Links to existing docs rather than duplicating them
  • No vague or overly verbose guidance
  • No temporary notes or TODOs (unless requested by the user)
  • No line numbers in file references
  • Focused on stable, long-term patterns
最终定稿前请检查：
  • 表述简洁，无重复内容
  • 所有章节仅提供非显而易见的价值
  • 未包含代码风格指南（改用代码检查工具）
  • 链接至现有文档而非重复内容
  • 无模糊或过于冗长的指导
  • 无临时注释或TODO项（除非用户要求）
  • 文件引用中未使用行号
  • 聚焦于稳定、长期的模式