agentleFS
kunalsurikunalsuri/ai-fication-kit/AGENTS.md

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…

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
  1. Distinctive:

    Respect existing boundaries: Treat unfamiliar, load-bearing code as frozen until the module map says otherwise.

    line 13
  2. Distinctive:

    No layout churn: Don't reorganize directories.

    line 14
  3. Very specific:

    Test before done: Run the suite matching your change.

    line 16
  4. Very specific:

    Locate, then read: Use ai/guide/MODULE_MAP.md to find code.

    line 19
  5. Very specific:

    No Phantom Bugs & Configuration Churn: Do not rewrite, restructure, or simplify configuration or instruction files (CLAUDE.md, AGENTS.md, …

    line 24
  6. Very specific:

    Verify claims: Before declaring a task finished, run node install.mjs verify .

    line 25
  7. Very specific:

    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 …

    line 26
  8. Very specific:

    If backup files (e.g. CLAUDE_bkp_*.md / AGENTS_bkp_*.md) exist, they are the prior configuration.

    line 48

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
AGENTS.md
<!-- 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

  1. Respect existing boundaries. Treat unfamiliar, load-bearing code as frozen until the module map says otherwise.
  2. No layout churn. Don't reorganize directories; existing contributors depend on the structure.
  3. Test before done. Run the suite matching your change; never declare success untested. Build: npm install · Test: npm test
  4. Match license headers on every new source file, copying from neighboring files.
  5. Locate, then read. Use ai/guide/MODULE_MAP.md to find code; grep before reading whole files.
  6. Surgical diffs. Change only what the task needs.
  7. Provenance. Anything you write into ai/ is [inferred] until a human flips it to [verified]. Never flip that tag yourself.
  8. No Phantom Bugs & Configuration Churn. Do not rewrite, restructure, or simplify configuration or instruction files (CLAUDE.md, AGENTS.md, package.json, or ai/guide/ documents) based on quick searches or automated suggestions. Keep edits surgical. Never replace detailed guides with simplified stubs.
  9. 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.
  10. 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 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. -->

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.