green-print
AGENTS.md1 starsChanged 17 days agoMITView on GitHub
A map and the rules an agent must not get wrong. Facts live in the docs it links (one fact, one home); this file stays short on purpose (tools/docs_check.py holds it under its line budget), because long instruction files are followed less well. Claude Code, Codex and Gemini CLI all read this file (CLAUDE.md imports it, .gemini/settings.json names it). Always: README.md and docs/README.md (the documentation map). Then only what the task touches: Conflict rule. A change that conflicts with an…
- Deletes or force-pushes
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 repository7 other files it gives its agents.
The file
We split this AGENTS.md into the rules it gives an agent
6 rules. About 1 is common, 4 are distinctive, and 1 is very specific to this project.
≈1
Common · estimate
Many files like this have a rule of this kind.
≈4
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 10
Always: README.md and docs/README.md (the documentation map).
- Distinctive: line 32
Decide or ask, never dangle: No menu of options at the end of a reply: ask with the question tool, or proceed on your recommendation and …
- Distinctive: line 42
Before calling a change done, walk this list and say which entries applied:
- Distinctive: line 47
Strings: no hard-coded user-facing text (ADR-012).
- Common: line 63
No secrets in the repo, in prompts or in logs.
- Distinctive: line 64
No AI attribution in commits, pull requests or comments.
≈ “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
Agent rules for GreenPrint
A map and the rules an agent must not get wrong. Facts live in the docs it links (one fact, one
home); this file stays short on purpose (tools/docs_check.py holds it under its line budget),
because long instruction files are followed less well. Claude Code, Codex and Gemini CLI all read
this file (CLAUDE.md imports it, .gemini/settings.json names it).
Read before you code
Always: README.md and docs/README.md (the documentation map). Then only what the task touches:
| If the task touches | Read |
| a feature a user sees | its spec in docs/features/ (write or extend it first; never invent one speculatively) |
| persistence, sync, the API | docs/architecture/overview.md (offline-first, write-through cache), ADR-002, ADR-003 |
| UI | docs/style_guide.md, ADR-012 (strings), ADR-013 (focus) |
| tests | docs/testing.md |
| a decision, a new dependency, a module | docs/architecture/decisions.md |
| how agents work here (skills, hooks, gates) | docs/agentic/README.md |
Conflict rule. A change that conflicts with an ADR: state the conflict and ask before going on. A decision that changes the architecture gets a new ADR in the same pull request.
Workflow
- Research. Map the code, check assumptions, reproduce a reported bug before fixing it.
- Strategy. A short plan; a written proposal when it is architectural.
- Execution. Plan, act, validate per sub-task. Done means run: the tests pass, the gate is clean, and you used what changed the way a user would (the app on a device, simulator, desktop or browser) and show the evidence (a screenshot, the output).
- Decide or ask, never dangle. No menu of options at the end of a reply: ask with the question tool, or proceed on your recommendation and say so.
- Work comes from issues. One issue, one branch, one worktree (
.agents/worktrees/<slug>), one pull request that closes it. Never commit tomain. - Delegate with intent. A lead agent plans, hands self-contained tasks to subagents, integrates
and reports. Pick each subagent's model and effort by the task's hardest step
(
docs/agentic/README.md, Subagents).
Hit every surface
Before calling a change done, walk this list and say which entries applied:
- Platforms: Android, iOS, Desktop (JVM), Web (Wasm); the server when the API changes.
- Offline: works without the server, syncs when it comes back (write-through cache).
- Reverse states: a way in needs a way out (create, edit, archive, delete, undo).
- Accessibility: content descriptions, keyboard focus order, touch targets.
- Strings: no hard-coded user-facing text (ADR-012).
- Docs: fix what the change makes wrong, in that fact's one home.
Gates (zero findings, no baseline)
./gradlew prePRcheckruns once before a pull request opens: ktlint, detekt, the shared, Compose UI and server tests, the Android and Wasm builds. A finding gets fixed; a suppression only at its line with the reason beside it, never a baseline or a raised threshold.- A docs or agent-files-only change runs
python3 tools/docs_check.pyinstead. - Merge only when every check is green and every review thread is resolved; never
--admin.
Guardrails
tools/agent_guard.py(a Claude CodePreToolUsehook) refuses destructive commands: pushes tomain, force pushes,--no-verify,git reset --hard, dropping or cleaning a database. A refusal is the owner's to run by hand, never worked around.- No secrets in the repo, in prompts or in logs. Credentials come from a vault at run time.
- No AI attribution in commits, pull requests or comments.
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.

