file-headers — Claude Code rule: a header in every source file
file-headers makes each source file open with a short, honest overview plus the exact line @author Son Nguyen <[email protected]>.
MIT ★ 1,198 updated 2026-10-23
.claude/rules/file-headers.mdWhat file-headers does
The rule covers .js, .ts, .tsx, .cjs, .mjs, .py, .sh and .css. Each of those files starts with a comment saying what the file actually does, then the exact author line. Dependencies, build output, data dumps, worktrees, minified or vendored code, the generated wiki/i18n-content.js and snapshots stay out of scope.
It binds the agent, not the developer. A new file gets its header before any code, and in shell scripts after the shebang. Touch a file with no header and the same change adds one. If your edit shifts what the file is for, the overview gets rewritten too.
The check is a script: bash .claude/skills/file-headers/scripts/check-headers.sh has to exit 0. Formats and the script both sit under .claude/skills/file-headers/, so the rule only polices a project where that skill is present. Installation is one file at .claude/rules/file-headers.md.
What it helps with
- add a header to a new file before the first commit
- restore the header a refactor stripped out
- rewrite the overview when a file's job changes
- audit author lines across the repo in one run
- fail the build when a source file ships without a header
Example prompts for the agent
- Create
src/metrics.tsand put the@author Son Nguyen <[email protected]>header on top before writing any code. scripts/deploy.shhas no header. Add one after the shebang and leave the logic alone.- Run
bash .claude/skills/file-headers/scripts/check-headers.shand fix every file it flags.
How to install file-headers
Manually: put the files in place
.claude/rules/file-headers.mdThe paths frontmatter field limits the files
AGENTS.md
Codex reads AGENTS.md: paste the rule text there
Manually: put the files in place
.cursor/rules/file-headers.mdcFrontmatter: description, globs, alwaysApply
Manually: put the files in place
.github/instructions/file-headers.instructions.mdThe applyTo field sets which files it applies to
Manually: put the files in place
.devin/rules/file-headers.mdManually: put the files in place
.clinerules/file-headers.mdStep by step, with commands for each platform: AGENTS.md vs CLAUDE.md: what they are and which one to use
Questions about file-headers
How do I install file-headers in Claude Code?
Place the rule file at .claude/rules/file-headers.md. Claude loads rules from that directory.
What does file-headers do?
It makes every applicable source file start with a short overview and the exact @author Son Nguyen <[email protected]> line. Files you merely edit get the header too.
How do I check that the whole repo complies?
Run bash .claude/skills/file-headers/scripts/check-headers.sh; it must exit 0. The script and the header formats live in .claude/skills/file-headers/.
Source text
file-headers.md · MIT
# File Header Rules (binding for every coding agent) - Every applicable source file (`.js/.ts/.tsx/.cjs/.mjs/.py/.sh/.css` — excluding `node_modules/`, `dist/`, `data/`, `.worktrees/`, minified/vendored, generated `wiki/i18n-content.js`, snapshots) MUST start with the header comment: a truthful file overview plus the exact line `@author Son Nguyen <[email protected]>`. - Creating a new applicable file → write the header before any code (after the shebang in scripts). - Editing a file that lacks the header → add it in the same change; if the edit changes the file's purpose, update the overview. - Formats and the repo-wide audit script live in `.claude/skills/file-headers/` (`bash .claude/skills/file-headers/scripts/check-headers.sh` must exit 0).
© hoangsonww · MIT · hoangsonww/Claude-Code-Agent-Monitor