Back to Details

agent-config-audit

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Agent Config Audit

Agent配置审计

Audit and maintain the full AI agent configuration stack across a workspace — CLAUDE.md, CODEX.md, AGENTS.md, .cursorrules, hooks, settings, and supporting 
.agents/
docs.
跨工作区审计并维护完整的AI Agent配置栈——包括CLAUDE.md、CODEX.md、AGENTS.md、.cursorrules、hooks、settings以及配套的
.agents/
文档。

When to Use

适用场景

  • User mentions: "audit CLAUDE.md", "agent config", "rules out of date", "config drift", "sync docs"
  • After restructuring repos, adding/removing projects, or changing conventions
  • Periodic maintenance (monthly recommended)
  • When agents keep making the same mistake despite rules existing (symptom of stale or contradictory config)
  • After a major refactor where file paths, package names, or architecture changed
  • 用户提及："audit CLAUDE.md"、"agent config"、"规则过时"、"配置偏差"、"同步文档"
  • 仓库重构、添加/移除项目或变更规范之后
  • 定期维护（建议每月一次）
  • 尽管已有规则，但Agent仍重复犯相同错误（这是配置过时或存在矛盾的表现）
  • 文件路径、包名或架构发生变更的重大重构之后

When NOT to Use

不适用场景

  • If writing actual application code → use bugfix, refactor-code, or repo-specific skills
  • If capturing a single new rule from conversation → use rules-capture
  • If auditing code quality / CRITICAL-NEVER-DO violations → use genfeed-codebase-audit
  • If checking formatter/linter configs (biome, prettier, tsconfig) → use genfeed-config-harmony
  • If scaffolding 
    .agents/
    from scratch → use agent-folder-init
  • 如果是编写实际应用代码→使用bugfix、refactor-code或仓库专属技能
  • 如果是从对话中提取单一新规则→使用rules-capture
  • 如果是审计代码质量/CRITICAL-NEVER-DO违规项→使用genfeed-codebase-audit
  • 如果是检查格式化工具/代码检查器配置（biome、prettier、tsconfig）→使用genfeed-config-harmony
  • 如果是从零开始搭建
    .agents/
    目录→使用agent-folder-init

Inputs

输入项

InputRequiredDescription
Workspace rootYesPath to the workspace containing repos (auto-detected from cwd)
ScopeNo
full
(all checks) or specific: 
dedup
, 
stale
, 
codex
, 
cursor
, 
settings
Fix modeNo
report
(default, read-only) or 
fix
(apply recommended changes)
输入项是否必填描述
工作区根目录是包含仓库的工作区路径（从当前工作目录自动检测）
范围否
full
（全量检查）或特定项：
dedup
、
stale
、
codex
、
cursor
、
settings
修复模式否
report
（默认，只读）或
fix
（应用推荐的变更）

Workflow

工作流程

Step 1: Inventory — Discover All Config Files

步骤1：盘点——发现所有配置文件

Scan the workspace for every agent config file:
bash
undefined
扫描工作区中的所有Agent配置文件：
bash
undefined

Find all agent config files across workspace (including sub-repos)

Find all agent config files across workspace (including sub-repos)

glob "/CLAUDE.md" glob "/CODEX.md" glob "/AGENTS.md" glob "/.cursorrules" glob "/.cursor/rules" glob "/.claude/settings.json" glob "/.claude/settings.local.json" glob "/.claude/hooks.json" glob "**/.agents/SYSTEM/critical/*.md"

Build an inventory table:
LayerFiles FoundTotal Lines
CLAUDE.mdNN
CODEX.mdNN
AGENTS.mdNN
.cursorrulesNN
.claude/ configNN
.agents/ systemNN
undefined
glob "/CLAUDE.md" glob "/CODEX.md" glob "/AGENTS.md" glob "/.cursorrules" glob "/.cursor/rules" glob "/.claude/settings.json" glob "/.claude/settings.local.json" glob "/.claude/hooks.json" glob "**/.agents/SYSTEM/critical/*.md"

构建盘点表格：
层级找到的文件数总行数
CLAUDE.mdNN
CODEX.mdNN
AGENTS.mdNN
.cursorrulesNN
.claude/ 配置NN
.agents/ 系统文档NN
undefined

Step 2: Dedup Check — Find Duplicated Rules

步骤2：去重检查——查找重复规则

These rules commonly appear in multiple places. Search for each across ALL config files:
Rules to check:
  • any
    types / 
    No any
    — should be in CLAUDE.md + hooks only
  • console.log
    / logger — should be in CLAUDE.md only
  • Conventional commits — should be in CLAUDE.md only
  • AbortController — should be in CLAUDE_RULES.md / repo CLAUDE.md only
  • Session file naming — should be in hooks.json + one doc reference only
  • Import order — should be in CLAUDE_RULES.md only
  • Soft delete (
    isDeleted
    ) — should be in CRITICAL-NEVER-DO.md only
  • Multi-tenancy (
    organization: orgId
    ) — should be in CRITICAL-NEVER-DO.md only
For each rule, count occurrences:
grep "No \`any\`\|NO \`any\`\|no any types" across all config files
Healthy target: Each rule appears in max 2 files (one "teach" doc + one runtime enforcement like hooks).
Flag: Any rule appearing 3+ times across config files.
以下规则常出现在多个位置，需在所有配置文件中逐一搜索：
待检查规则：
  • any
    类型 / 
    No any
    — 仅应出现在CLAUDE.md和hooks中
  • console.log
    / 日志器 — 仅应出现在CLAUDE.md中
  • 约定式提交 — 仅应出现在CLAUDE.md中
  • AbortController — 仅应出现在CLAUDE_RULES.md/仓库专属CLAUDE.md中
  • 会话文件命名 — 仅应出现在hooks.json和一份文档引用中
  • 导入顺序 — 仅应出现在CLAUDE_RULES.md中
  • 软删除（
    isDeleted
    ） — 仅应出现在CRITICAL-NEVER-DO.md中
  • 多租户（
    organization: orgId
    ） — 仅应出现在CRITICAL-NEVER-DO.md中
统计每条规则的出现次数：
grep "No \`any\`\|NO \`any\`\|no any types" across all config files
健康目标：每条规则最多出现在2个文件中（一份“教学”文档 + 一份运行时强制执行文件如hooks）。
标记：任何在配置文件中出现3次及以上的规则。

Step 3: Staleness Check — Find Outdated Files

步骤3：过时检查——查找过期文件

Check for stale dates and paths:
bash
undefined
检查过期日期和路径：
bash
undefined

Find files with old "Last Updated" dates (> 90 days old)

Find files with old "Last Updated" dates (> 90 days old)

grep -r "Last Updated:" across .cursorrules, .cursor/rules
grep -r "Last Updated:" across .cursorrules, .cursor/rules

Find hardcoded workspace paths that should be relative

Find hardcoded workspace paths that should be relative

grep -r "/Users/" across .agents/ config files
grep -r "/Users/" across .agents/ config files

Find references to directories that no longer exist

Find references to directories that no longer exist

Compare referenced paths against actual directory listing

Compare referenced paths against actual directory listing


**Flag**: Any file with "Last Updated" > 90 days behind current date.
**Flag**: Any hardcoded absolute path in config files.
**Flag**: Any reference to a directory that doesn't exist.

**标记**：任何“Last Updated”日期距当前日期超过90天的文件。
**标记**：配置文件中存在任何硬编码的绝对路径。
**标记**：任何指向已不存在目录的引用。

Step 4: CODEX.md Value Check

步骤4：CODEX.md价值检查

For each CODEX.md, check if it has:
  • Codex-specific constraints (sandbox, no network, no interactive)
  • Repo-specific entry points (key files to read first)
  • NOT just "read CLAUDE.md" (that's a zero-value redirect stub)
bash
grep -l "Codex-Specific\|sandbox\|no network\|No network" across all CODEX.md files
Flag: Any CODEX.md without Codex-specific guidance.
对每个CODEX.md，检查是否包含：
  • Codex专属约束（沙箱、无网络、无交互）
  • 仓库专属入口点（优先读取的关键文件）
  • 不只是“阅读CLAUDE.md”（这是无价值的重定向占位符）
bash
grep -l "Codex-Specific\|sandbox\|no network\|No network" across all CODEX.md files
标记：任何未包含Codex专属指导的CODEX.md。

Step 5: AGENTS.md Consistency Check

步骤5：AGENTS.md一致性检查

For each AGENTS.md:
  • Has repo-specific context (not just generic "docs in .agents/")
  • Links to correct 
    .agents/
    paths that actually exist
  • Consistent structure across repos
Flag: Any AGENTS.md that's a pure generic stub (< 20 lines with no repo-specific content).
对每个AGENTS.md：
  • 包含仓库专属上下文（不只是通用的“.agents/中的文档”）
  • 链接到实际存在的
    .agents/
    路径
  • 跨仓库结构一致
标记：任何纯通用占位符的AGENTS.md（少于20行且无仓库专属内容）。

Step 6: Cursor Config Check

步骤6：Cursor配置检查

For 
.cursorrules
and 
.cursor/rules
:
  • No emoji in headers (wastes tokens)
  • "Last Updated" within 90 days
  • Project paths reference actual directories
  • No duplicated session file rules (hooks.json handles this)
对
.cursorrules
和
.cursor/rules
：
  • 标题中无表情符号（会浪费令牌）
  • “Last Updated”日期在90天以内
  • 项目路径指向实际存在的目录
  • 无重复的会话文件规则（由hooks.json处理）

Step 7: Settings Audit

步骤7：设置审计

For 
.claude/settings.json
and 
.claude/settings.local.json
:
  • Denied skills have documented rationale (in SETTINGS-NOTES.md or equivalent)
  • Local bash overrides don't contradict documented standards without explanation
  • No stale tool references
对
.claude/settings.json
和
.claude/settings.local.json
：
  • 被禁用的技能有文档化的理由（在SETTINGS-NOTES.md或等效文件中）
  • 本地bash覆盖项若无解释，不得与文档化标准冲突
  • 无过时的工具引用

Step 8: Generate Report

步骤8：生成报告

Output format:
markdown
undefined
输出格式：
markdown
undefined

Agent Config Audit Report

Agent配置审计报告

Date: YYYY-MM-DD Workspace: [path] Files Scanned: N
日期： YYYY-MM-DD 工作区： [路径] 扫描文件数： N

Summary

摘要

  • Critical issues: N
  • Moderate issues: N
  • Minor issues: N
  • Total config lines: N (target: reduce by dedup)
  • 严重问题：N
  • 中等问题：N
  • 轻微问题：N
  • 配置总行数：N（目标：通过去重减少行数）

Critical: Rule Duplication

严重：规则重复

RuleOccurrencesFilesTarget
"No any types"6[list]2
规则出现次数文件列表目标次数
"No any types"6[列表]2

Critical: Stale Files

严重：过期文件

FileLast UpdatedDays Stale
文件最后更新日期过期天数

Moderate: Low-Value CODEX.md

中等：低价值CODEX.md

FileLinesHas Codex ConstraintsHas Entry Points
文件行数是否包含Codex约束是否包含入口点

Moderate: Stub AGENTS.md

中等：占位符AGENTS.md

FileLinesHas Repo Context
文件行数是否包含仓库上下文

Minor: Emoji in Config

轻微：配置中的表情符号

FileEmoji Count
文件表情符号数量

Recommendations

建议

  1. [Specific actionable fix]
  2. [Specific actionable fix]
undefined
  1. [具体可执行的修复方案]
  2. [具体可执行的修复方案]
undefined

Step 9: Apply Fixes (if fix mode)

步骤9：应用修复（若启用修复模式）

If user requested 
fix
mode, apply changes following these principles:
  • Each rule lives in ONE canonical location
  • Hooks enforce at runtime — docs teach, not repeat
  • Strip emoji from all config files
  • Update all "Last Updated" dates
  • Replace hardcoded paths with relative references
  • Expand zero-value CODEX.md stubs with Codex-specific constraints
如果用户请求
fix
模式，需遵循以下原则应用变更：
  • 每条规则仅存在于一个标准位置
  • Hooks负责运行时强制执行——文档用于教学，而非重复规则
  • 移除所有配置文件中的表情符号
  • 更新所有“Last Updated”日期
  • 将硬编码路径替换为相对引用
  • 为无价值的CODEX.md占位符添加Codex专属约束

Reference Files

参考文件

  • references/canonical-ownership.md
    — Which rule belongs in which file
  • references/healthy-config-example.md
    — Example of a well-structured config set
  • references/canonical-ownership.md
    — 每条规则应归属的文件
  • references/healthy-config-example.md
    — 结构良好的配置集示例

Anti-Patterns

反模式

DON'TDOWhy
Repeat the same rule in CLAUDE.md, RULES.md, CRITICAL-NEVER-DO.md, and hooksPut the rule in ONE canonical file; others reference itDuplication wastes context tokens and creates drift when one copy gets updated but others don't
Leave "Last Updated: 2025-10-07" in a file touched in 2026Update dates when modifying any config fileStale dates signal neglect and erode trust in the config system
Write CODEX.md that just says "read CLAUDE.md"Add Codex-specific constraints (sandbox, no network) and key entry pointsCodex runs sandboxed — it needs different guidance than Claude Code
Use emoji in config headersUse plain text headersEmoji waste tokens on every context load and violate "no emoji unless requested"
Hardcode 
/Users/username/path/
in config files		Use relative paths or describe location genericallyHardcoded paths break when workspace moves or another developer joins
Add new rules to CRITICAL-NEVER-DO.md that are positive standardsKeep CRITICAL-NEVER-DO.md for violations only; positive standards go in CLAUDE.md or RULES.mdMixing positive and negative rules in the same file dilutes the "NEVER DO" signal
禁止做法正确做法原因
在CLAUDE.md、RULES.md、CRITICAL-NEVER-DO.md和hooks中重复相同规则将规则放在一个标准文件中；其他文件仅引用它重复会浪费上下文令牌，且当其中一份副本更新而其他未更新时会导致配置偏差
文件最后更新日期仍为“Last Updated: 2025-10-07”但在2026年已修改修改任何配置文件时更新日期过期日期会显示出配置被忽视，降低用户对配置系统的信任
CODEX.md仅写“阅读CLAUDE.md”添加Codex专属约束（沙箱、无网络）和关键入口点Codex运行在沙箱环境中——它需要与Claude Code不同的指导
在配置标题中使用表情符号使用纯文本标题表情符号会在每次加载上下文时浪费令牌，且违反“除非要求否则不使用表情符号”的规则
在配置文件中硬编码
/Users/username/path/
使用相对路径或通用描述位置当工作区移动或其他开发者加入时，硬编码路径会失效
将新的正向规则添加到CRITICAL-NEVER-DO.md中仅在CRITICAL-NEVER-DO.md中保留禁止项；正向规则放在CLAUDE.md或RULES.md中在同一文件中混合正向和负向规则会削弱“绝对禁止”的信号

Validation

验证

After running the audit:
  • No rule appears in more than 2 config files
  • All 
    .cursorrules
    files have "Last Updated" within 90 days
  • Every CODEX.md has Codex-specific sandbox guidance
  • No hardcoded absolute paths in any config file
  • No emoji in 
    .cursorrules
    or 
    .cursor/rules
    headers
  • Denied skills in settings.json have documented rationale
  • Total config file line count decreased or stayed flat (no bloat)
运行审计后需确认：
  • 没有规则在超过2个配置文件中出现
  • 所有
    .cursorrules
    文件的“Last Updated”日期在90天以内
  • 每个CODEX.md都包含Codex专属沙箱指导
  • 所有配置文件中无硬编码绝对路径
  • .cursorrules
    或
    .cursor/rules
    标题中无表情符号
  • settings.json中被禁用的技能有文档化的理由
  • 配置文件总行数减少或保持稳定（无冗余）

Related Skills

相关技能

  • rules-capture — Route here if user is expressing a new rule during conversation (not auditing)
  • agent-folder-init — Route here if scaffolding 
    .agents/
    structure from scratch
  • genfeed-config-harmony — Route here if the issue is formatter/linter configs (biome, prettier, tsconfig)
  • genfeed-codebase-audit — Route here if auditing code quality, not config quality
  • claude-md-management:revise-claude-md — Route here if updating a single CLAUDE.md with session learnings (not full audit)
  • claude-md-management:claude-md-improver — Complementary; focuses on individual CLAUDE.md quality while this skill focuses on cross-file consistency
  • rules-capture — 若用户在对话中表达新规则（而非审计），请转至此技能
  • agent-folder-init — 若从零开始搭建
    .agents/
    结构，请转至此技能
  • genfeed-config-harmony — 若问题涉及格式化工具/代码检查器配置（biome、prettier、tsconfig），请转至此技能
  • genfeed-codebase-audit — 若审计代码质量而非配置质量，请转至此技能
  • claude-md-management:revise-claude-md — 若使用会话中的经验更新单个CLAUDE.md（而非全量审计），请转至此技能
  • claude-md-management:claude-md-improver — 互补技能；该技能专注于单个CLAUDE.md的质量，而本技能专注于跨文件一致性