ai-fication-kit
AGENTS.md3 starsChanged 4 months agoApache-2.0View on GitHub
Tool-agnostic instructions for any AI coding agent (Claude Code, Codex, Cursor, Copilot, Windsurf). Claude Code reads these via @AGENTS.md in CLAUDE.md (see CLAUDE.md); other tools read this file directly. Generated analysis (on demand): ai/analysis/ — feature catalog, audit reports, diagrams. Development intelligence: ai/lab/ — specs, ADRs, evaluations, and the feature roadmap (ai/lab/ROADMAP.md, planned backlog + shipped index). Machine-readable facts: ai/repo-profile.json (produced deterministically by the kit's orient step — trust it for stack facts, verify before relying on commands). If backup…
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 32,671 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository32 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- .github/copilot-instructions.mdCopilot instructions
- .cursor/rules/add-feature.mdcCursor rule
- .cursor/rules/adversarial-audit.mdcCursor rule
- .cursor/rules/ai-knowledge-layer.mdcCursor rule
- .cursor/rules/check-drift.mdcCursor rule
- .cursor/rules/cold-start.mdcCursor rule
- .cursor/rules/create-feature-catalog.mdcCursor rule
- .cursor/rules/fix-bug.mdcCursor rule
- .cursor/rules/perform-feature-add-simulation.mdcCursor rule
- .cursor/rules/post-cold-start-verification.mdcCursor rule
- .cursor/rules/review-agent-config.mdcCursor rule
- .cursor/rules/review-change.mdcCursor rule
- .cursor/rules/verify-ai-readiness.mdcCursor rule
- add-featureSkill
- cold-startSkill
- deep-testSkill
- fix-bugSkill
- review-changeSkill
- add-featureSkill
- adversarial-auditSkill
- check-docsSkill
- check-driftSkill
- cold-startSkill
- create-feature-catalogSkill
- fix-bugSkill
- implement-specSkill
- perform-feature-add-simulationSkill
- post-cold-start-verificationSkill
- review-agent-configSkill
- review-changeSkill
- verify-ai-readinessSkill
The file
We split this AGENTS.md into the rules it gives an agent
8 rules. About 0 are common, 2 are distinctive, and 6 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
6
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 13
Respect existing boundaries: Treat unfamiliar, load-bearing code as frozen until the module map says otherwise.
- Distinctive: line 14
No layout churn: Don't reorganize directories.
- Very specific: line 16
Test before done: Run the suite matching your change.
- Very specific: line 19
Locate, then read: Use ai/guide/MODULE_MAP.md to find code.
- Very specific: line 24
No Phantom Bugs & Configuration Churn: Do not rewrite, restructure, or simplify configuration or instruction files (CLAUDE.md, AGENTS.md, …
- Very specific: line 25
Verify claims: Before declaring a task finished, run node install.mjs verify .
- Very specific: line 26
Record work: Every unit of work ends with an appended row in ai/lab/WORKLOG.md linking its spec, review, and commits — even work done …
- Very specific: line 48
If backup files (e.g. CLAUDE_bkp_*.md / AGENTS_bkp_*.md) exist, they are the prior configuration.
≈ “Common” is an estimate: at least 1 in 5 of the 41,581 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
<!-- Copyright (c) 2026 Kunal Suri (CEA LIST). All rights reserved. -->AGENTS.md — ai-fication-kit
Tool-agnostic instructions for any AI coding agent (Claude Code, Codex, Cursor,
Copilot, Windsurf). Claude Code reads these via @AGENTS.md in CLAUDE.md (see CLAUDE.md);
other tools read this file directly.
Project
A Toolkit to Give AI Coding Agents a Trusted Map of Any Existing/Legacy Repo Stack: JavaScript/TypeScript.
Rules every agent must follow
- Respect existing boundaries. Treat unfamiliar, load-bearing code as frozen until the module map says otherwise.
- No layout churn. Don't reorganize directories; existing contributors depend on the structure.
- Test before done. Run the suite matching your change; never declare success
untested. Build:
npm install· Test:npm test - Match license headers on every new source file, copying from neighboring files.
- Locate, then read. Use
ai/guide/MODULE_MAP.mdto find code; grep before reading whole files. - Surgical diffs. Change only what the task needs.
- Provenance. Anything you write into
ai/is[inferred]until a human flips it to[verified]. Never flip that tag yourself. - No Phantom Bugs & Configuration Churn. Do not rewrite, restructure, or simplify configuration or instruction files (
CLAUDE.md,AGENTS.md,package.json, orai/guide/documents) based on quick searches or automated suggestions. Keep edits surgical. Never replace detailed guides with simplified stubs. - Verify claims. Before declaring a task finished, run
node install.mjs verify . --strict(or equivalent test runner validation script) to ensure no file paths in the knowledge documents are broken. - Record work. Every unit of work ends with an appended row in
ai/lab/WORKLOG.mdlinking its spec, review, and commits — even work done outside the command workflows.
Knowledge map
Navigation (fast path): ai/guide/MODULE_MAP.md (where code lives),
ai/guide/ARCHITECTURE.md (system shape), ai/guide/FEATURE_MAP.md (feature → files
- gotchas),
ai/guide/CONVENTIONS.md(how to write code here).
Generated analysis (on demand): ai/analysis/ — feature catalog, audit reports,
diagrams. Development intelligence: ai/lab/ — specs, ADRs, evaluations, and
the feature roadmap (ai/lab/ROADMAP.md, planned backlog + shipped index).
Machine-readable facts: ai/repo-profile.json (produced deterministically by the
kit's orient step — trust it for stack facts, verify before relying on commands).
Repo intelligence (the ai/ knowledge-base)
The ai/ folder is the single source of truth for repository intelligence. It is
tool-agnostic: any AI coding agent (Claude, Cursor, Copilot, Codex) reads the same
verified maps, architecture docs, and feature catalogs. New features, refactors, and
onboarding all start here. A tool's private per-machine memory (e.g. Claude Code
auto-memory) is not shared — record durable knowledge in the committed ai/ layer so
every agent and teammate sees it.
If backup files (e.g. CLAUDE_bkp_*.md / AGENTS_bkp_*.md) exist, they are the prior
configuration. Knowledge was extracted from them during /cold-start — use ai/guide/
as the authoritative source instead.
<!-- Installed by ai-fication-kit 0.1.0 on 2026-06-17. -->Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

