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.

Источник