agentleFS
Sign inStart free
KletoWorksKletoWorks/complex-md/AGENTS.md

complex-md

AGENTS.md1 starsChanged 17 days agoMITView on GitHub

complex-md has two parts: the cli/ npm package and the complex.md site. These rules are for a coding agent that works on either part. - Run cd cli && npm test before you finish a change. The exit code is the gate, not the printed summary. CI runs it on Ubuntu, Windows and macOS, each with Node 22 and 24. - Run npm run build at the root after a change to content/, site/ or scripts/build.mjs. It writes dist/. -…

  • 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 31,843 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 repository4 other files it gives its agents.

The file

We split this AGENTS.md into the rules it gives an agent

11 rules. About 0 are common, 1 is distinctive, and 10 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈1

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 10

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  • could be automatic: a setting could enforce it
  1. Very specific:

    Run cd cli && npm test before you finish a change.

    line 8
  2. Very specific:

    Run npm run build at the root after a change to content/, site/ or scripts/build.mjs.

    line 11
  3. Very specific:

    Add no runtime dependency to cli/package.json.

    line 15
  4. Very specific:

    Add no network call. The only requests are the model calls in cli/src/generate.js, and cli/test/telemetry.test.js fails on any other.

    line 18
  5. Very specific:

    When CLI behavior changes, run cd cli && node --test test/truth.test.js.

    line 21
  6. Very specific:

    Do not run bench/run.mjs unless you are asked to.

    line 23
  7. Very specific:

    Do not edit COMPLEX.md, .claude/rules/ or the section below by hand.

    line 25
  8. Distinctive:

    Write a commit subject in conventional form, 72 characters at most.

    line 32
  9. Very specific:

    Follow the AI assistance policy in CONTRIBUTING.md: disclose the tool in the pull request description, add an Assisted-by: or a …

    line 36
  10. Very specific:

    When editing one file of a co_change pair, or a file in one side of a seams pair, open the partner and state in your change description …

    line 54
  11. Very specific:

    After refactoring a listed hotspot, regenerate the map: npx complex-md, or run the complex-md skill.

    line 63

≈ “Common” is an estimate: at least 1 in 5 of the 40,246 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

AGENTS.md

Working on this repository

complex-md has two parts: the cli/ npm package and the complex.md site. These rules are for a coding agent that works on either part.

  • Run cd cli && npm test before you finish a change. The exit code is the gate, not the printed summary. CI runs it on Ubuntu, Windows and macOS, each with Node 22 and 24.
  • Run npm run build at the root after a change to content/, site/ or scripts/build.mjs. It writes dist/.
  • Edit the prompts in prompts/. The files in cli/prompts/ are copies that cli/scripts/sync-prompts.mjs makes before each pack.
  • Add no runtime dependency to cli/package.json. The core has none. The MCP server in packages/complex-md-mcp imports the MCP SDK and zod only. Run cd packages/complex-md-mcp && npm test after a change there.
  • Add no network call. The only requests are the model calls in cli/src/generate.js, and cli/test/telemetry.test.js fails on any other.
  • When CLI behavior changes, run cd cli && node --test test/truth.test.js. It fails on a public sentence that the code contradicts.
  • Do not run bench/run.mjs unless you are asked to. It drives a real agent and spends the account's usage.
  • Do not edit COMPLEX.md, .claude/rules/ or the section below by hand. They are generated. Regenerate them with node cli/bin/complex-md.js, which prints the next step when no provider key is set.
  • The repository commits no edit hooks and no MCP server config. To try the hooks on your own clone, run node cli/bin/complex-md.js wire --hooks --local. It writes them to Claude Code's per user settings file, which stays out of commits.
  • Write a commit subject in conventional form, 72 characters at most. In the body, state the problem before the fix. Use numbers, not adjectives.
  • A change to the spec or a signal cites a benchmark run or a source, and adds a line to CHANGELOG.md.
  • Follow the AI assistance policy in CONTRIBUTING.md: disclose the tool in the pull request description, add an Assisted-by: or a Co-Authored-By: trailer, and leave the review of the diff and the answers to review comments to a person. Fill in each section of .github/PULL_REQUEST_TEMPLATE.md, including the AI assistance box.
<!-- BEGIN complex-md (spec 0.3) -->

COMPLEX.md: the structural risk map

COMPLEX.md at the repository root is a computed map of where edits are risky and where bugs get fixed, built from the dependency graph and the commit history. Its hotspots, load_bearing, co_change and seams lists name specific files and areas. When your work touches one of them:

  1. IMPORTANT: before editing a file listed under hotspots or load_bearing, read its paragraph in COMPLEX.md under "Why these files are hot" and do what that paragraph's last sentence says before you change the file.
  2. When editing one file of a co_change pair, or a file in one side of a seams pair, open the partner and state in your change description whether the partner also needed a change.
  3. Fixing a bug whose location you do not yet know, check the hotspots rows with the highest fixes count before searching the whole repository; past fixes predict where the next one lands.
  4. Entering this repository cold, read the files under "What to read first" in order before your first edit.

After refactoring a listed hotspot, regenerate the map: npx complex-md, or run the complex-md skill.

<!-- END complex-md (spec 0.3) -->

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.

Check your setup, free