Back to Details

agent-config

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

User Input

用户输入

text
$ARGUMENTS
Consider user input for:
  • create
    - Create new file from scratch
  • update
    - Improve existing file
  • audit
    - Analyze and report on current file quality
  • A specific path (e.g., 
    src/api/CLAUDE.md
    for directory-specific instructions)
text
$ARGUMENTS
请根据用户输入执行对应操作：
  • create
    - 从头创建新文件
  • update
    - 改进现有文件
  • audit
    - 分析并报告当前文件质量
  • 指定路径（例如：
    src/api/CLAUDE.md
    用于特定目录的指令）

Step 1: Determine Target File

步骤1：确定目标文件

If not specified in user input, ask the user which file type to work with:
CLAUDE.md - Project context file loaded at the start of every conversation. Contains:
  • Bash commands Claude cannot guess
  • Code style rules that differ from defaults
  • Testing instructions and preferred test runners
  • Repository etiquette (branch naming, PR conventions)
  • Architectural decisions specific to the project
  • Developer environment quirks (required env vars)
  • Common gotchas or non-obvious behaviors
AGENTS.md - Custom subagent definitions file. Contains:
  • Specialized assistant definitions
  • Tool permissions for each agent
  • Model preferences (opus, sonnet, haiku)
  • Focused instructions for isolated tasks
如果用户输入中未指定，请询问用户要处理的文件类型：
CLAUDE.md - 每次对话开始时加载的项目上下文文件。包含以下内容：
  • Claude无法推测的Bash命令
  • 与默认规则不同的代码风格规范
  • 测试指令和首选测试运行器
  • 仓库礼仪（分支命名、PR规范）
  • 项目特有的架构决策
  • 开发环境的特殊要求（必填环境变量）
  • 常见陷阱或非直观行为
AGENTS.md - 自定义子Agent定义文件。包含以下内容：
  • 专业助手定义
  • 每个Agent的工具权限
  • 模型偏好（opus、sonnet、haiku）
  • 针对特定任务的聚焦指令

CLAUDE.md Guidelines

CLAUDE.md 指南

Based on official Claude Code documentation.
基于官方Claude Code文档。

Core Principle

核心原则

CLAUDE.md is a special file Claude reads at the start of every conversation. Include Bash commands, code style, and workflow rules. This gives Claude persistent context it cannot infer from code alone.
CLAUDE.md是Claude在每次对话开始时都会读取的特殊文件。文件中需包含Bash命令、代码风格和工作流规则。这能为Claude提供仅通过代码无法推断的持久上下文信息。

What to Include

内容规范

✅ Include❌ Exclude
Bash commands Claude cannot guessAnything Claude can figure out by reading code
Code style rules that differ from defaultsStandard language conventions Claude already knows
Testing instructions and preferred test runnersDetailed API documentation (link to docs instead)
Repository etiquette (branch naming, PR conventions)Information that changes frequently
Architectural decisions specific to your projectLong explanations or tutorials
Developer environment quirks (required env vars)File-by-file descriptions of the codebase
Common gotchas or non-obvious behaviorsSelf-evident practices like "write clean code"
✅ 需包含内容❌ 需排除内容
Claude无法推测的Bash命令Claude通过阅读代码即可获知的内容
与默认规则不同的代码风格规范Claude已熟知的标准语言约定
测试指令和首选测试运行器详细的API文档（改为链接到文档）
仓库礼仪（分支命名、PR规范）频繁变更的信息
项目特有的架构决策冗长的解释或教程
开发环境的特殊要求（必填环境变量）逐文件的代码库描述
常见陷阱或非直观行为诸如“编写整洁代码”这类不言自明的做法

Quality Test

质量检测

For each line, ask: "Would removing this cause Claude to make mistakes?" If not, cut it.
If Claude keeps ignoring a rule, the file is probably too long and the rule is getting lost. If Claude asks questions answered in CLAUDE.md, the phrasing might be ambiguous.
对于每一行内容，请问自己：“删除这一行会导致Claude犯错吗？” 如果不会，就删掉。
如果Claude持续忽略某条规则，可能是文件过长导致规则被淹没。如果Claude提出的问题在CLAUDE.md中已有答案，可能是规则的表述不够清晰。

Example Format

示例格式

markdown
undefined
markdown
undefined

Code style

代码风格

  • Use ES modules (import/export) syntax, not CommonJS (require)
  • Destructure imports when possible (eg. import { foo } from 'bar')
  • 使用ES模块（import/export）语法，而非CommonJS（require）
  • 尽可能使用解构导入（例如：import { foo } from 'bar'）

Workflow

工作流

  • Be sure to typecheck when you're done making a series of code changes
  • Prefer running single tests, and not the whole test suite, for performance
undefined
  • 完成一系列代码更改后务必进行类型检查
  • 为提升性能，优先运行单个测试，而非整个测试套件
undefined

File Locations

文件位置

  • Home folder (
    ~/.claude/CLAUDE.md
    )    : Applies to all Claude sessions
  • Project root (
    ./CLAUDE.md
    )    : Check into git to share with your team
  • Local only (
    CLAUDE.local.md
    )    : Add to 
    .gitignore
    for personal overrides
  • Parent directories: Useful for monorepos where both 
    root/CLAUDE.md
    and 
    root/foo/CLAUDE.md
    are pulled in automatically
  • Child directories: Claude pulls in child CLAUDE.md files on demand
  • 主目录（
    ~/.claude/CLAUDE.md
    ）    ：适用于所有Claude会话
  • 项目根目录（
    ./CLAUDE.md
    ）    ：提交到git以便团队共享
  • 本地专属（
    CLAUDE.local.md
    ）    ：添加到
    .gitignore
    用于个人自定义配置
  • 父目录：适用于单体仓库，
    root/CLAUDE.md
    和
    root/foo/CLAUDE.md
    会被自动加载
  • 子目录：Claude会按需加载子目录中的CLAUDE.md文件

Import Syntax

导入语法

CLAUDE.md files can import additional files using 
@path/to/import
syntax:
markdown
See @README.md for project overview and @package.json for available npm commands.
CLAUDE.md文件可使用
@path/to/import
语法导入其他文件：
markdown
项目概览请查看@README.md，可用npm命令请查看@package.json。

Additional Instructions

额外指令

  • Git workflow: @docs/git-instructions.md
  • Personal overrides: @~/.claude/my-project-instructions.md
undefined
  • Git工作流：@docs/git-instructions.md
  • 个人自定义配置：@~/.claude/my-project-instructions.md
undefined

Emphasis for Critical Rules

关键规则强调

Add emphasis (e.g., "IMPORTANT" or "YOU MUST") to improve adherence for critical rules.
可添加强调标识（例如：“IMPORTANT”或“YOU MUST”）来提升关键规则的遵循度。

AGENTS.md Guidelines

AGENTS.md 指南

Custom subagents run in their own context with their own set of allowed tools. Useful for tasks that read many files or need specialized focus.
自定义子Agent在独立上下文环境中运行，并拥有专属的允许使用的工具集。适用于需要读取大量文件或需要专业聚焦的任务。

Agent Definition Format

Agent定义格式

markdown
---
name: security-reviewer
description: Reviews code for security vulnerabilities
tools: Read, Grep, Glob, Bash
model: opus
---
You are a senior security engineer. Review code for:
- Injection vulnerabilities (SQL, XSS, command injection)
- Authentication and authorization flaws
- Secrets or credentials in code
- Insecure data handling

Provide specific line references and suggested fixes.
markdown
---
name: security-reviewer
description: 审查代码中的安全漏洞
tools: Read, Grep, Glob, Bash
model: opus
---
你是一名资深安全工程师。请审查代码中的以下问题：
- 注入漏洞（SQL、XSS、命令注入）
- 认证与授权缺陷
- 代码中的密钥或凭证
- 不安全的数据处理方式

请提供具体的行号引用和建议修复方案。

Required Fields

必填字段

  • name: Identifier to invoke the agent
  • description: What the agent does (helps Claude decide when to use it)
  • tools: Comma-separated list of allowed tools (Read, Grep, Glob, Bash, Edit, Write, etc.)
  • name：用于调用Agent的标识符
  • description：Agent的功能描述（帮助Claude决定何时使用该Agent）
  • tools：允许使用的工具列表，用逗号分隔（Read、Grep、Glob、Bash、Edit、Write等）

Optional Fields

可选字段

  • model: Preferred model (opus, sonnet, haiku)
  • model：首选模型（opus、sonnet、haiku）

Best Practices for Agents

Agent最佳实践

  1. Keep agent instructions focused on a single domain
  2. Be specific about what the agent should look for
  3. Request concrete output formats (line references, specific fixes)
  4. Limit tool access to what's actually needed
  1. 保持Agent指令聚焦于单一领域
  2. 明确指定Agent需要检查的内容
  3. 要求具体的输出格式（行号引用、具体修复方案）
  4. 限制工具访问权限，仅授予实际需要的工具

Execution Flow

执行流程

For 
create
or default:

针对
create
或默认场景：

  1. Ask which file type (CLAUDE.md or AGENTS.md) if not specified
  2. Analyze the project:
    • Check for existing files at standard locations
    • Identify technology stack, project type, development tools
    • Review README.md, CONTRIBUTING.md, package.json, etc.
  3. Draft the file following guidelines above
  4. Present draft for review
  5. Write to appropriate location after approval
  1. 若未指定文件类型，询问用户是CLAUDE.md还是AGENTS.md
  2. 分析项目：
    • 检查标准位置是否存在现有文件
    • 识别技术栈、项目类型、开发工具
    • 查看README.md、CONTRIBUTING.md、package.json等文件
  3. 按照上述指南起草文件
  4. 提交草稿供用户审核
  5. 获得批准后写入对应位置

For 
update
:

针对
update
场景：

  1. Read existing file
  2. Audit against best practices
  3. Identify:
    • Content to remove (redundant, obvious, style rules)
    • Content to condense
    • Missing essential information
  4. Present changes for review
  5. Apply changes after approval
  1. 读取现有文件
  2. 对照最佳实践进行审核
  3. 识别：
    • 需要删除的内容（冗余、显而易见的内容、风格规则）
    • 需要精简的内容
    • 缺失的关键信息
  4. 提交变更供用户审核
  5. 获得批准后应用变更

For 
audit
:

针对
audit
场景：

  1. Read existing file
  2. Generate a report with:
    • Assessment of content quality
    • List of anti-patterns found
    • Percentage of truly useful vs redundant content
    • Specific recommendations for improvement
  3. Do NOT modify the file, only report
  1. 读取现有文件
  2. 生成包含以下内容的报告：
    • 内容质量评估
    • 发现的反模式列表
    • 有用内容与冗余内容的占比
    • 具体的改进建议
  3. 请勿修改文件，仅生成报告

Anti-Patterns to Avoid

需避免的反模式

DO NOT include:
  • Code style guidelines (use linters/formatters)
  • Generic best practices Claude already knows
  • Long explanations of obvious patterns
  • Copy-pasted code examples
  • Information that changes frequently
  • Instructions for specific one-time tasks
  • File-by-file codebase descriptions
请勿包含以下内容：
  • 代码风格指南（使用代码检查器/格式化工具）
  • Claude已熟知的通用最佳实践
  • 对显而易见模式的冗长解释
  • 复制粘贴的代码示例
  • 频繁变更的信息
  • 针对特定一次性任务的指令
  • 逐文件的代码库描述

Notes

注意事项

  • Run 
    /init
    to generate a starter CLAUDE.md based on current project structure
  • Treat CLAUDE.md like code: review it when things go wrong, prune it regularly
  • Check CLAUDE.md into git so your team can contribute
  • The file compounds in value over time as you refine it
  • 运行
    /init
    可基于当前项目结构生成初始版CLAUDE.md
  • 像对待代码一样对待CLAUDE.md：出现问题时进行审查，定期精简内容
  • 将CLAUDE.md提交到git，以便团队成员共同维护
  • 随着不断优化，该文件的价值会逐渐提升