reviewing-claude-config

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Reviewing Claude Configuration

审查Claude配置

Instructions

说明

IMPORTANT: Use structured thinking throughout your review process. Plan your analysis before providing feedback. This improves accuracy and catches critical security issues.

重要提示：在整个审查过程中请使用结构化思维。在给出反馈前先规划好你的分析思路。这能提升准确性并发现关键安全问题。

Step 1: Detect File Type

步骤1：检测文件类型

<thinking> Analyze the changed files: 1. Which .claude files were modified? 2. What file types? (CLAUDE.md, skills, agents, prompts, commands, settings) 3. Are there immediate security concerns? 4. What's the review scope (single file or multiple)? </thinking>

Determine the primary file type(s) being reviewed:

Detection Rules:

Agents: Changes to

.claude/agents/*.md

plugins/*/agents/*.md

Skills: Changes to
```
skill.md
```
files or skill support files (checklists, references, examples)
CLAUDE.md: Changes to
```
CLAUDE.md
```
files (any location: project root,
```
.claude/
```
, or subdirectories)

Prompts/Commands: Changes to

.claude/prompts/*.md

.claude/commands/*.md

Settings: Changes to

.claude/settings.json

.claude/settings.local.json

If multiple types modified, review each with appropriate checklist.

<thinking> 分析已变更的文件： 1. 哪些.claude文件被修改了？ 2. 文件类型是什么？（CLAUDE.md、技能、Agent、提示词、命令、设置） 3. 是否存在即时的安全隐患？ 4. 审查范围是单个文件还是多个文件？ </thinking>

确定正在审查的主要文件类型：

检测规则：

Agent：修改了

.claude/agents/*.md

或

plugins/*/agents/*.md

技能：修改了
```
skill.md
```
文件或技能支持文件（检查清单、参考资料、示例）
CLAUDE.md：修改了CLAUDE.md文件（任意位置：项目根目录、.claude/或子目录）

提示词/命令：修改了

.claude/prompts/*.md

或

.claude/commands/*.md

设置：修改了

.claude/settings.json

或

.claude/settings.local.json

如果修改了多种类型的文件，请针对每种类型使用相应的检查清单进行审查。

Step 2: Execute Security Scan (ALWAYS)

步骤2：执行安全扫描（必须执行）

<thinking> Security first, regardless of file type: 1. Is settings.local.json committed to git? 2. Any hardcoded secrets (passwords, tokens, API keys)? 3. Are permissions appropriately scoped (if settings modified)? 4. Any suspicious patterns in changed files? </thinking>

CRITICAL CHECKS (perform for ALL Claude config reviews):

Run these mental checks immediately:

settings.local.json NOT in git (check changed files list)
No hardcoded credentials in any modified files
Permissions scoped appropriately (if settings.json modified)
No API keys, tokens, or passwords in plaintext

If ANY security issue found: Flag as CRITICAL immediately, stop and report.

Consult

reference/security-patterns.md

for detailed security checks and detection commands.

<thinking> 安全优先，无论文件类型如何： 1. settings.local.json是否被提交到git？ 2. 是否存在硬编码的密钥（密码、令牌、API密钥）？ 3. 权限范围是否设置得当（如果修改了设置）？ 4. 已变更的文件中是否存在可疑模式？ </thinking>

关键检查项（所有Claude配置审查都必须执行）：

立即进行以下检查：

settings.local.json 未提交到git（检查已变更文件列表）
所有已修改文件中无硬编码凭证
权限范围设置得当（如果修改了settings.json）
无明文存储的API密钥、令牌或密码

如果发现任何安全问题：立即标记为CRITICAL（关键），停止审查并上报。

如需详细的安全检查和检测命令，请查阅

reference/security-patterns.md

。

Step 3: Load Appropriate Checklist

步骤3：加载对应的检查清单

Based on detected file type, read and follow the relevant checklist:

Agents →
```
checklists/agents.md
```
(YAML, tool access security, model selection, system prompts)
Skills →
```
checklists/skills.md
```
(structure, YAML, progressive disclosure, quality)
CLAUDE.md →
```
checklists/claude-md.md
```
(clarity, references, no duplication)
Prompts/Commands →
```
checklists/prompts.md
```
(purpose, session context, skill references)
Settings →
```
checklists/settings.md
```
(security, permissions scoping)

The checklist provides:

Multi-pass review strategy
What to check and what to skip
Structured thinking guidance
Common issues and red flags

根据检测到的文件类型，阅读并遵循相关的检查清单：

Agent →
```
checklists/agents.md
```
（YAML、工具访问安全性、模型选择、系统提示词）
技能 →
```
checklists/skills.md
```
（结构、YAML、渐进式披露、质量）
CLAUDE.md →
```
checklists/claude-md.md
```
（清晰度、参考资料、无重复内容）
提示词/命令 →
```
checklists/prompts.md
```
（用途、会话上下文、技能参考）
设置 →
```
checklists/settings.md
```
（安全性、权限范围划分）

检查清单提供：

多轮次审查策略
需要检查和可以跳过的内容
结构化思维指导
常见问题和危险信号

Step 4: Consult Reference Materials As Needed

步骤4：按需查阅参考资料

<thinking> When to load references: 1. Need to classify issue priority? → priority-framework.md 2. Security patterns unclear? → security-patterns.md 3. Claude Code requirements (YAML, tools, models, limits)? → claude-code-requirements.md </thinking>

Load reference files only when needed for specific questions:

Issue prioritization →
```
reference/priority-framework.md
```
(CRITICAL vs IMPORTANT vs SUGGESTED vs OPTIONAL)
Security patterns →
```
reference/security-patterns.md
```
(detection commands, fix examples)
Claude Code requirements →
```
reference/claude-code-requirements.md
```
(YAML frontmatter, model selection, tool names, progressive disclosure, settings conventions)

<thinking> 何时加载参考资料： 1. 需要对问题优先级进行分类？→ priority-framework.md 2. 安全模式不明确？→ security-patterns.md 3. Claude Code的要求（YAML、工具、模型、限制）？→ claude-code-requirements.md </thinking>

仅在针对特定问题需要时加载参考文件：

问题优先级划分 →
```
reference/priority-framework.md
```
（CRITICAL vs IMPORTANT vs SUGGESTED vs OPTIONAL）
安全模式 →
```
reference/security-patterns.md
```
（检测命令、修复示例）
Claude Code要求 →
```
reference/claude-code-requirements.md
```
（YAML前置元数据、模型选择、工具名称、渐进式披露、设置约定）

Step 5: Document Findings

步骤5：记录发现的问题

<thinking> Before writing each comment: 1. Priority level? (Critical/Important/Suggested/Optional) 2. Security issue or quality issue? 3. What's the specific fix or recommendation? 4. What's the rationale (why does this matter)? 5. Is there a reference or documentation link? </thinking>

This section defines the standard output format for ALL Claude config reviews. Checklists reference this section rather than duplicating content.

CRITICAL: Use inline comments on specific lines, NOT one large summary comment.

Inline Comment Rules:

Create separate comment for EACH specific issue on the exact line
Do NOT create one large summary comment with all issues
Do NOT update existing comments - always create new comments
Include specific fix with code example when applicable
Explain rationale (why this matters)

Comment Format:

**[file:line]** - [PRIORITY]: [Issue description]

[Specific fix with code example if applicable]

[Rationale explaining why this matters]

Reference: [documentation link if applicable]

Example inline comment:

**.claude/skills/my-skill/skill.md:1** - CRITICAL: Missing YAML frontmatter

Skills require YAML frontmatter to be discoverable by Claude Code:

\```yaml
---
name: my-skill
description: Clear description with activation triggers
---
\```

Without frontmatter, the skill won't be recognized by Claude Code.

Reference: Anthropic Skills Documentation

When to use inline vs summary:

Inline comment: Specific issue, recommendation, or question (use
```
file:line
```
format)
Summary comment: Overall assessment, recommendation (APPROVE or REQUEST CHANGES)

Load the specific example relevant to your file type (on-demand only, not upfront):

Agents →
```
examples/example-agent-review.md
```
Skills →
```
examples/example-skill-review.md
```
CLAUDE.md →
```
examples/example-claude-md-review.md
```
Settings →
```
examples/example-settings-review.md
```
Prompts →
```
examples/example-prompts-review.md
```

<thinking> 在撰写每条评论前： 1. 优先级级别？（Critical/Important/Suggested/Optional） 2. 是安全问题还是质量问题？ 3. 具体的修复方案或建议是什么？ 4. 理由是什么（为什么这很重要）？ 5. 是否有参考资料或文档链接？ </thinking>

本部分定义了所有Claude配置审查的标准输出格式。 检查清单会引用本部分内容，而非重复相关信息。

重要提示：对具体行使用内联评论，不要使用一个大的汇总评论。

内联评论规则：

针对每个具体问题在对应行创建单独的评论
不要创建一个包含所有问题的大汇总评论
不要更新现有评论 - 始终创建新评论
适用时包含具体的修复方案及代码示例
解释理由（为什么这很重要）

评论格式：

**[文件:行号]** - [优先级]: [问题描述]

[适用时提供具体修复方案及代码示例]

[解释为什么这很重要的理由]

参考资料: [适用时提供文档链接]

内联评论示例：

**.claude/skills/my-skill/skill.md:1** - CRITICAL: 缺少YAML前置元数据

技能需要YAML前置元数据才能被Claude Code识别：

\```yaml
---
name: my-skill
description: 包含触发条件的清晰描述
---
\```

如果没有前置元数据，该技能将无法被Claude Code识别。

参考资料：Anthropic Skills Documentation

何时使用内联评论 vs 汇总评论：

内联评论：针对特定问题、建议或疑问（使用
```
文件:行号
```
格式）
汇总评论：整体评估、建议（批准或请求变更）

按需加载与文件类型对应的具体示例（仅在需要时加载，无需提前加载）：

Agent →
```
examples/example-agent-review.md
```
技能 →
```
examples/example-skill-review.md
```
CLAUDE.md →
```
examples/example-claude-md-review.md
```
设置 →
```
examples/example-settings-review.md
```
提示词 →
```
examples/example-prompts-review.md
```

Core Principles

核心原则

Security first: Always check for committed settings, secrets, overly broad permissions
Structure matters: YAML frontmatter, file references, progressive disclosure, line limits
Quality counts: Clear instructions, examples, proper emphasis, structured thinking
Token efficiency: Progressive disclosure, appropriate file sizes, on-demand loading
Actionable feedback: Say what to do and why, not just what's wrong
Constructive tone: Focus on code/config, not people; explain rationale

安全优先：始终检查已提交的设置、密钥、过宽的权限
结构至关重要：YAML前置元数据、文件引用、渐进式披露、行数限制
质量至上：清晰的说明、示例、适当的强调、结构化思维
Token效率：渐进式披露、合适的文件大小、按需加载
可执行的反馈：说明要做什么以及原因，而不只是指出问题
建设性语气：聚焦于代码/配置，而非个人；解释理由