best-practices-audit

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Best Practices Audit

最佳实践审计

You are auditing a project's CLAUDE.md to ensure it follows Anthropic's official best practices and stays effective as the project evolves. This runs after compound learnings are captured, to catch any drift.

您正在审计项目的CLAUDE.md文件，确保其遵循Anthropic的官方最佳实践，并在项目演进过程中保持有效性。此流程在捕获复合学习内容后运行，以发现任何偏离情况。

When to Activate

激活时机

Invoked by the
```
ship
```
command after compound-learnings
The
```
/workflows:setup-claude-md
```
command includes similar audit logic
After significant CLAUDE.md changes

由
```
ship
```
命令在复合学习完成后调用
```
/workflows:setup-claude-md
```
命令包含类似的审计逻辑
在CLAUDE.md发生重大变更后

Reference

参考资料

Read the best-practices reference from

.claude/skills/setup-claude-md/claude-code-best-practices.md

. If the file is not accessible, use the audit checklist below as the authoritative guide.

阅读

.claude/skills/setup-claude-md/claude-code-best-practices.md

中的最佳实践参考文档。若无法访问该文件，请以下面的审计检查清单作为权威指南。

Audit Checklist

审计检查清单

1. Size Check

1. 篇幅检查

CLAUDE.md should be under ~100 lines. Performance degrades with length.

Under 80 lines: Good
80-120 lines: Acceptable, look for extraction opportunities
Over 120 lines: Must extract sections to
```
docs/
```
with
```
@import
```

CLAUDE.md的篇幅应控制在约100行以内，篇幅过长会降低性能。

80行以内：良好
80-120行：可接受，需寻找可提取的内容
120行以上：必须将部分章节提取至
```
docs/
```
目录并使用@import引用

2. Required Sections

2. 必备章节

Every CLAUDE.md should have (in this order):

undefined

每个CLAUDE.md都应包含以下章节（按此顺序）：

undefined

Build & Test Commands — How to build, test, lint, typecheck

Build & Test Commands — 构建、测试、代码检查、类型校验的方法

Code Conventions — Only non-obvious, project-specific ones

Code Conventions — 仅包含非通用的、项目特定的规范

Architecture Decisions — Key patterns and data flow

Architecture Decisions — 核心模式与数据流

Gotchas & Workarounds — Things that will bite you

Gotchas & Workarounds — 易踩坑点与解决方案


Optional but valuable:


可选但有价值的章节：

Environment Setup — env vars, secrets, dependencies

Environment Setup — 环境变量、密钥、依赖项

Workflow Rules — branch, commit, PR conventions

Workflow Rules — 分支、提交、PR规范


Flag missing required sections.


标记缺失的必备章节。

3. @import Structure

3. @import结构规范

Detailed documentation should be extracted to

docs/

and referenced via

@import

markdown

undefined

详细文档应提取至

docs/

目录，并通过@import引用：

markdown

undefined

CLAUDE.md (short, focused)

@docs/api-conventions.md @docs/data-model.md @docs/deployment.md


**Check for**:
- Sections over ~10 lines that are domain-specific → extract to `docs/`
- Architecture docs inline → extract to `docs/architecture.md`
- Convention details inline → extract to `docs/conventions.md`
- API documentation inline → extract or use context7 instead

@docs/api-conventions.md @docs/data-model.md @docs/deployment.md


**检查要点**：
- 超过10行的领域特定章节 → 提取至`docs/`
- 内联的架构文档 → 提取至`docs/architecture.md`
- 内联的规范细节 → 提取至`docs/conventions.md`
- 内联的API文档 → 提取或使用context7替代

4. Auto-Exclude Patterns

4. 自动排除模式

Flag and suggest removal of:

Pattern	Why
Standard language conventions	Claude already knows these
"Write clean code" / "Follow best practices"	Self-evident
Detailed API documentation	Link to docs or use context7
File-by-file codebase descriptions	Claude can read the code
Long explanations or tutorials	Extract to docs/
Information that changes frequently	Will go stale quickly
Generic advice not specific to this project	Adds noise without value

标记并建议移除以下内容：

模式	原因
标准语言规范	Claude已内置相关知识
"编写整洁代码" / "遵循最佳实践"	内容不言自明
详细的API文档	链接至文档或使用context7
逐文件的代码库描述	Claude可直接读取代码
长篇解释或教程	提取至docs/目录
频繁变更的信息	极易过时
非项目特定的通用建议	仅增加冗余无实际价值

5. Command Accuracy

5. 命令准确性验证

Verify all commands in CLAUDE.md actually work:

Read
```
package.json
```
scripts (or equivalent)
Cross-reference with CLAUDE.md build/test/lint commands
Flag any commands that don't match reality:
- Command listed but script doesn't exist
- Script exists but command not listed
- Command syntax is wrong

验证CLAUDE.md中所有命令是否实际可用：

读取
```
package.json
```
中的脚本（或等效文件）
与CLAUDE.md中的构建/测试/代码检查命令交叉对比
标记任何与实际不符的命令：
- 命令已列出但对应的脚本不存在
- 脚本存在但未在CLAUDE.md中列出
- 命令语法错误

6. Hook Candidates

6. 钩子候选规则识别

Identify CLAUDE.md rules that should be deterministic hooks instead:

"Always run lint before committing" → pre-commit hook
"Never use
```
any
```
type" → TypeScript strict config
"Format with Prettier" → PostToolUse format hook
"Check for secrets before pushing" → PreToolUse hook

Advisory rules that can be enforced deterministically should be hooks, not CLAUDE.md lines.

识别应转为确定性钩子的CLAUDE.md规则：

"提交前必须运行代码检查" → 提交前钩子（pre-commit hook）
"禁止使用
```
any
```
类型" → TypeScript严格配置
"使用Prettier格式化代码" → PostToolUse格式化钩子
"推送前检查是否包含密钥" → PreToolUse钩子

可被确定性执行的建议规则应转为钩子，而非保留在CLAUDE.md中。

7. Staleness Check

7. 过时内容检查

Look for entries that reference:

Files that no longer exist
Patterns that were replaced
Dependencies that were removed
Commands that were changed
Conventions that evolved

查找引用以下内容的条目：

已不存在的文件
已被替代的模式
已移除的依赖项
已变更的命令
已演进的规范

Auto-Fix vs Flag

自动修复 vs 标记提醒

Auto-Fix (do silently)

自动修复（静默执行）

Reorder sections to match the recommended order
Remove obviously self-evident entries ("write clean code")
Fix command syntax if the correct command is clear from
```
package.json
```
Extract sections over 10 lines to
```
docs/
```
with
```
@import
```
(create the file)

按照推荐顺序重新排列章节
移除明显不言自明的条目（如"编写整洁代码"）
若从
```
package.json
```
可明确得知正确命令，则修复命令语法
将超过10行的章节提取至
```
docs/
```
目录并添加@import引用（自动创建文件）

Flag for Developer (ask before changing)

标记提醒（需确认后修改）

Removing content that might be intentional
Changing conventions that affect team workflow
Adding new sections based on codebase analysis
Pruning entries you're not 100% certain are stale

移除可能为有意保留的内容
修改影响团队工作流的规范
基于代码库分析添加新章节
修剪您无法100%确定已过时的条目

Report

报告模板

undefined

undefined

CLAUDE.md Audit

CLAUDE.md审计报告

Size: [N] lines ([status: good / needs extraction / critical])

Auto-fixed:

[list of changes made automatically]

Needs your input:

[list of flagged items with context]

Recommendations:

[suggestions for improvement]

Hook candidates:

[rules that should become hooks]

undefined

篇幅：[N]行（状态：良好 / 需要提取内容 / 严重过长）

已自动修复:

[自动修复的变更列表]

需要您确认:

[标记项及上下文说明]

建议:

[改进建议]

钩子候选规则:

[应转为钩子的规则]

undefined

Rules

规则

Every line in CLAUDE.md should earn its place — one precise instruction is worth ten generic ones
Auto-fix structural issues but never auto-remove content without flagging
The goal is a CLAUDE.md that makes agents maximally effective, not one that documents everything
Reference
```
_shared/validation-pattern.md
```
for self-checking
Prefer
```
@import
```
for anything that would make the core file unwieldy
Don't add sections for the sake of completeness — only add what's genuinely useful

CLAUDE.md中的每一行都应有存在的价值——一条精准的指令胜过十条通用建议
自动修复结构问题，但绝不自动移除内容，需移除时必须标记提醒
目标是打造能让Agent发挥最大效能的CLAUDE.md，而非记录所有内容
参考
```
_shared/validation-pattern.md
```
进行自我检查
任何会导致核心文件过于冗长的内容，优先使用@import引用
不要为了完整性而添加章节——仅保留真正有用的内容