Documentation, audit, or commit gate: three postures for CLAUDE.md and AGENTS.md

说明与用途

提交门检查 CLAUDE.md 和 AGENTS.md 的大小、引用完整性和结构，防止无声错误，保持指令文件可维护。

问题

Instruction files for AI agents grow large, become unmaintainable, and can contain dangling or orphaned references, leading to silent failures and lack of ownership.

结果

The commit‑gate enforces mechanical correctness of instruction files, preventing size bloat, dangling references, and orphaned skills, while keeping prose readable and reducing manual audit effort.

工作流

• 1. Write or update CLAUDE.md and AGENTS.md in prose.
• 2. Run pnpm test which executes test/ops/claude-md-structure.test.ts before every commit.
• 3. The test suite checks: size ceiling, no dangling skill references, no orphaned skills, non‑empty skill descriptions, skill line limits, and required paths in front‑matter.
• 4. If any check fails, the commit is rejected and the developer must fix the issue.
• 5. Successful commits are merged, and the gate acts as the reviewer of record for all non‑human‑reviewed changes.

证据

The instruction file "slowly becomes a second codebase, except without the compiler, tests, or clear ownership."

来源

test/ops/claude-md-structure.test.ts reads the real files on disk and asserts six things.

来源