agent-config-audit

Agent 配置审计

授权范围

仅在用户请求和现有授权范围内操作；加载此技能不会赋予任何新权限。仅提供报告的请求必须只提供报告，遵守调用方对目标、主机、提供方和成本的限制，扩展范围前先征求同意，并将这些限制传达给委派对象。

契约

输入：

• 工作区根目录
• 范围：full、dedup、stale、instructions、cursor、settings 或 fix
• 可选的要纳入检查的仓库／配置文件列表

输出：

• 包含严重、中等和轻微问题的审计报告
• 建议的修复计划
• 仅在明确指定修复模式时应用更改

创建／修改：

• 报告模式：不更改文件
• 修复模式：仅在明确请求修复并确认确切计划后，修改 Agent 配置文件、.agents/ 文档及相关设置

外部副作用：

• 默认无
• 不会推送、发布或调用外部 API

所需确认：

• 进入修复模式或使用任何会修改内容的文件／shell 操作之前；仅请求审计或同步时只授权报告模式
• 覆盖现有 Agent 配置之前
• 删除或合并重复规则之前

委派给：

• 单条新增偏好交给 rules-capture
• 缺少 .agents/ 结构时交给 agent-folder-init

适用场景

• 用户提到：“审计 CLAUDE.md”“Agent 配置”“规则过时”“配置漂移”“同步文档”
• 重构仓库、添加／移除项目或更改约定之后
• 定期维护（建议每月一次）
• 尽管已有规则，Agent 仍反复犯同样的错误（这是配置过时或互相矛盾的迹象）
• 文件路径、包名称或架构发生变化的重大重构之后

不适用场景

• 对于应用缺陷，建议使用 debug；对于重构，建议使用 /refactor。
• 如果要从对话中记录一条新规则 → 使用 rules-capture
• 如果要审计代码质量而非 Agent 配置 → 使用 audit
• 如果要设置或修复格式化工具／linter 配置 → 使用 linter-formatter-init
• 如果要从头搭建 .agents/ → 使用 agent-folder-init

输入

输入	必需	描述
工作区根目录	是	包含仓库的工作区路径（从 cwd 自动检测）
范围	否	full（所有检查）或指定范围：dedup、stale、instructions、cursor、settings
修复模式	否	report（默认，只读）或 fix（应用建议的更改）

工作流

步骤 1：清点 — 找出所有配置文件

扫描工作区，查找所有 Agent 配置文件：

# Find all agent config files across workspace (including sub-repos)
glob "**/CLAUDE.md"
glob "**/AGENTS.override.md"
glob "**/AGENTS.md"
glob "**/.cursorrules"
glob "**/.cursor/rules"
glob "**/.claude/settings.json"
glob "**/.claude/settings.local.json"
glob "**/.claude/hooks.json"
glob "**/.agents/memory/*.md"

建立清点表：

| Layer           | Files Found | Total Lines |
|-----------------|-------------|-------------|
| CLAUDE.md       | N           | N           |
| AGENTS.override.md | N        | N           |
| AGENTS.md       | N           | N           |
| Configured fallbacks | N      | N           |
| .cursorrules    | N           | N           |
| .claude/ config | N           | N           |
| .agents/memory/ | N           | N           |

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

这些规则通常会出现在多个位置。请在所有配置文件中搜索每条规则：

要检查的规则：

• any 类型／No any — 应仅出现在 AGENTS.md 和 hooks 中
• console.log／logger — 应仅出现在 AGENTS.md 中
• Conventional commits — 应仅出现在 AGENTS.md 中
• AbortController — 应仅出现在 AGENTS.md 或链接的 .agents/memory/ 主题中
• 会话文件命名 — 应仅出现在 hooks.json 和一处文档引用中
• 导入顺序 — 应仅出现在 AGENTS.md 或 .agents/memory/coding-standards.md 中
• 软删除（isDeleted）— 应仅出现在 .agents/memory/data-guardrails.md 中
• 多租户（organization: orgId）— 应仅出现在 .agents/memory/security.md 中

对每条规则统计出现次数：

grep "No \`any\`\|NO \`any\`\|no any types" across all config files

理想目标：每条规则最多出现在 2 个文件中（一个“讲解”文档 + 一项运行时强制措施，例如 hooks）。

标记：任何规则在 3 个或更多配置文件中出现。

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

检查过时的日期和路径：

# Find files with old "Last Updated" dates (> 90 days old)
grep -r "Last Updated:" across .cursorrules, .cursor/rules

# Find hardcoded workspace paths that should be relative
grep -r "/Users/" across .agents/ config files

# Find references to directories that no longer exist
# Compare referenced paths against actual directory listing

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

第 4 步：Codex 指令解析检查

对于每个工作区，检查 Codex 实际解析的指令链：

• 每个目录最多解析一个非空指令文件，优先顺序为：AGENTS.override.md、AGENTS.md，然后是已配置的后备文件名
• 指令链从项目根目录向下读取至工作目录
• 仅当某个子树有意替换同目录下的 AGENTS.md 时，才使用 AGENTS.override.md
• AGENTS.md 包含仓库专属规则和入口
• 所有后备文件名都在生效的 .codex/config.toml 中明确声明
• 运行时审批、沙箱和网络策略位于生效的 .codex/config.toml 或钩子中，而不是仅存在于假定的说明文字中
• 没有将 .codex/instructions.md 文件或 .codex/commands 目录呈现为受支持的 Codex 入口 表面

在评估指令链之前，先读取生效的 Codex 配置，并记录 project_doc_fallback_filenames 以及任何运行时策略。

标记：未记录的后备文件、意外覆盖、与运行时配置矛盾的指令文件，或不受支持的 .codex/instructions.md 和 .codex/commands 表面。

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

对于每个 AGENTS.md：

• 包含仓库专属背景信息（而不只是泛泛地写“文档位于 .agents/”）
• 链接指向实际存在的正确 .agents/ 路径
• 各仓库的结构保持一致

标记：任何纯通用的 AGENTS.md 占位文件（少于 20 行且不含仓库专属内容）。

第 6 步：Cursor 配置检查

对于 .cursorrules 和 .cursor/rules：

• 标题中没有表情符号（会浪费令牌）
• “Last Updated” 日期在最近 90 天内
• 项目路径指向实际目录
• 没有重复的会话文件规则（hooks.json 负责处理此项）

第 7 步：设置审计

对于 .claude/settings.json 和 .claude/settings.local.json：

• 被拒绝的技能有记录在案的理由（见 SETTINGS-NOTES.md 或同等文件）
• 本地 bash 覆盖项不会在缺少说明的情况下与已记录的标准矛盾
• 没有过时的工具引用

第 8 步：生成报告

输出格式：

# Agent Config Audit Report
**Date:** YYYY-MM-DD
**Workspace:** [path]
**Files Scanned:** N

## Summary
- Critical issues: N
- Moderate issues: N
- Minor issues: N
- Total config lines: N (target: reduce by dedup)

## Critical: Rule Duplication
| Rule | Occurrences | Files | Target |
|------|-------------|-------|--------|
| "No any types" | 6 | [list] | 2 |

## Critical: Stale Files
| File | Last Updated | Days Stale |
|------|-------------|------------|

## Moderate: Instruction Resolution Drift
| Workspace | Override | AGENTS.md | Configured Fallbacks | Runtime Policy Location |
|-----------|----------|-----------|----------------------|-------------------------|

## Moderate: Stub AGENTS.md
| File | Lines | Has Repo Context |
|------|-------|------------------|

## Minor: Emoji in Config
| File | Emoji Count |
|------|-------------|

## Recommendations
1. [Specific actionable fix]
2. [Specific actionable fix]

第 9 步：应用修复（如果处于修复模式）

切勿根据审计结果或“同步”配置的请求推断进入修复模式。只有在用户明确要求修改时才进入修复模式；先展示确切的文件和操作，并在使用写入/编辑或执行会产生修改的 shell 操作前获得确认。随后按照以下原则应用更改：

• 每条规则只放在一个规范位置
• 钩子在运行时执行强制检查——文档负责说明，不要重复规则
• 从所有配置文件中移除表情符号
• 更新所有“Last Updated”日期
• 将硬编码路径替换为相对引用
• 将项目指令整合到 AGENTS.md 和作用域明确的 AGENTS.override.md 文件中
• 将运行时审批、沙箱和网络策略移入生效的 .codex/config.toml 或钩子中

参考文件

• references/canonical-ownership.md — 各类规则应归属哪个文件
• references/healthy-config-example.md — 结构良好的配置集示例
• 文件指针：所选 skill-creator 技能目录中的 references/writing-for-agents.md，用于判断一条引导规则是否值得加载（缓存与环境、沉积、膨胀）

反模式

不要	应该	原因
在 AGENTS.md、CLAUDE.md、.agents/memory/ 和钩子中重复同一条规则	将规则放在一个规范文件中；其他位置引用它	重复会浪费上下文令牌；如果更新了一处副本而其他副本未更新，就会造成不一致
在 2026 年修改的文件中保留“Last Updated: 2025-10-07”	修改任何配置文件时更新日期	过时的日期会显得疏于维护，削弱人们对配置系统的信任
创建额外的指令文件名，却不进行配置	将共享项目指南放在 AGENTS.md 中；使用 AGENTS.override.md 进行范围限定的覆盖，并在生效的 .codex/config.toml 中配置任何实际需要的备用文件	Codex 会解析原生指令文件名以及明确配置的备用文件
在配置标题中使用表情符号	使用纯文本标题	每次加载上下文时，表情符号都会浪费令牌，也违反“除非明确要求，否则不使用表情符号”的原则
在配置文件中硬编码 /Users/username/path/	使用相对路径或概括性地描述位置	工作区移动或有其他开发者加入时，硬编码路径会失效
在 .agents/ 下重新创建一套平行的旧版指令目录结构	将持久性防护规则放在 .agents/memory/ 下的主题文件中；将共享且可执行的规则放在 AGENTS.md 中	当前的记忆布局让持久性上下文易于发现，同时避免创建平行层级结构

验证

完成审计后：

• 每条规则出现的配置文件不超过 2 个
• 所有 .cursorrules 文件中的“Last Updated”日期都在最近 90 天内
• 每个 Codex 指令文件都是原生文件（AGENTS.override.md 或 AGENTS.md），或是明确配置的备用文件
• 运行时审批、沙盒和网络相关声明与生效的 .codex/config.toml 或钩子一致
• 所有配置文件中都没有硬编码的绝对路径
• .cursorrules 或 .cursor/rules 标题中没有表情符号
• settings.json 中被拒绝的技能都有记录在案的理由
• 配置文件的总行数有所减少或保持不变（没有臃肿）

相关技能

• rules-capture — 记录一项新偏好，而不是审计一组配置
• agent-folder-init — 初始化缺失的 .agents/ 结构
• linter-formatter-init — 设置或修复格式化工具／代码检查工具配置
• audit — 审计应用质量，而不是 Agent 配置