Rules Go in AGENTS.md, Facts Come From the Stack
An instructions file should hold decisions people made. Anything a running system can report should come from the running system.
An instructions file should hold decisions people made. Anything a running system can report should come from the running system.
AGENTS.md files tend to grow until they describe the system instead of governing it. Then the system changes and the file keeps insisting on the old version.
Two kinds of sentence
Read any long instructions file and you will find two kinds of sentence mixed together. One kind is a rule: sign off every commit, never commit a .env, migrations run in a migrator, not in a start script. The other kind is a fact: the API listens on 4000, the web app is at this URL, Postgres is the database.
Rules change when people decide to change them. Facts change when someone edits a service.json on a Tuesday. If both live in the same file, the facts rot first, and an assistant trusts a stale fact exactly as much as a current rule.
Rules are cheap to keep true
A rule is a decision. It is short, it has a reason, and it stays correct until someone argues with it in a pull request. These are the lines that belong in AGENTS.md:
- What must never be hand-edited, and which source file to change instead.
- Which command verifies the change, and what a pass looks like.
- Where a boundary sits, for example that environment checks and generated-file checks are different commands.
- What the team has already decided not to do, so nobody re-opens it at 2am.
Facts should have one author
Everything in the second list can be read off a running Flisk stack. flisk status --json reports health, readiness and ingress URLs. flisk resources lists services with their stack, type and port. flisk networks shows the Traefik URL of each frontend and API and whether it answers.
If a fact is in the instructions file as well, you have two authors for it, and one of them is a person who will forget. Delete the sentence and point at the command instead.
What the file looks like afterwards
Shorter, and more trusted. Instead of a paragraph describing the services, one line:
Run `flisk status --json` for what is running and where.
Never edit .flisk/ or *.autogenerated.*; change service.json instead.The assistant gets the same information, from the one place that cannot be out of date, and the file now contains only things a human had to decide.