AI conventions — AGENTS.md

How a model actually reads it

An AI tool with access to your repository looks for a conventions file before it answers. Finding one, it places the contents into the model's context ahead of your question — so the model reads your standing instructions first and your immediate request second. That ordering is the whole mechanism: the file does not configure a setting somewhere, it changes what the model has already read by the time it starts composing an answer.

Three consequences follow, and they are the reason a good file looks different from a bad one:

• Length costs you. Every line occupies context that could hold your actual work. Forty useful lines beat four hundred aspirational ones.
• Specifics survive; adjectives do not. "Be rigorous" changes nothing. "Every statistic you give me is a draft until I verify it against a source" changes what the model writes.
• It is read every session, so it compounds. A correction you write down once stops recurring. A correction you deliver in chat is gone tomorrow.

A baseline to start from

This is adapted from the conventions file of a production software repository, reduced to the parts that are not specific to any one project. Copy it, then edit until it describes you rather than a generic student — a file you did not write will not match how you actually work, and you will stop trusting it within a week.

# AI conventions

## About this repository
One-line description of what this repo is and who owns it.
Canonical file: AGENTS.md. CLAUDE.md points here.

## Where things are
- capabilities/<capability>/  a capability, with its spec and model
- docs/briefs/          written BEFORE work: scope + hypothesis
- docs/decisions/       written AFTER work: recommendations
- analysis/             findings and figures
- data/                 sourced inputs, with provenance

## Naming
- The directory matters most. A file in the wrong folder may not be found
  at all. If you are not certain which folder a file belongs in, ask me
  before you write it — do not choose for me.
- Graded files use the exact filename the stage brief gives — lowercase,
  hyphens, no spaces. Some courses date-stamp (YYYY-MM-DD-lastname-slug.md);
  the stage page says so when they do.
- Slugs name the engagement, never the week, the course, or the assignment
  number.
- Never invent a path or a filename. I will give you the exact one.

## How I work
- Explain concepts fully and walk the worked example. Do not hand me conclusions.
- Critique my reasoning directly. I would rather be corrected than agreed with.
- When you are uncertain, say so and say what would resolve it.

## What you may and may not draft
- You MAY explain, critique, debug, quiz me, and draft mechanical files.
- You MAY NOT write my briefs, analyses, memos, or reflections.
- Every statistic or figure you give me is a draft until I verify it against a source.

## Documentation
When work changes, update the document that describes it in the same commit.
A capability's README names the engagements that exercised it — keep that current.

## Scope
Do the work I asked for. If you notice something worth doing that I did not ask
for, tell me instead of doing it.

## Commits
Descriptive messages: what changed and why. Never "update" or "stuff".

## Never include
No credentials, no API keys, no personal data about anyone, no licensed or
copyrighted material. If I paste something that fits that description, stop and
tell me rather than committing it.

## Mistakes to avoid (append to this list)
Record errors here as they happen, so the same one does not repeat.
- (empty — add the first one when it happens)

The last section is the one that matters

Most people write a conventions file once, at setup, and never open it again. The habit worth building is the opposite: when a model gets something wrong, write it down. The wrong formula it kept reaching for, the citation it invented, the convention it ignored twice — one line each, in the mistakes section.

This turns a static preferences file into an accumulating record of how your tools fail on your work, and it is the single highest-value thing in the file. It is also invisible to anyone who has never maintained one, which is why it is called out here rather than left to be discovered.

What must never go in the repository

The repository is public and the conventions file is read by tools you do not control. Both facts point the same direction.

The same list governs what you paste into a model. If a document would not be safe in a public repository, it is not safe in a chat window either — treat both as publication. Removing a file in a later commit does not remove it from the history; see why history is permanent.

Who drafts first

If the artifact is evidence of your judgment, you draft it first and AI reviews; if the artifact is a means to the work rather than the work itself, AI may draft it and you verify. Briefs, analyses, memos, and reflections are evidence — a model cannot produce them on your behalf without destroying the thing they document. Folder skeletons, .gitignore files, formatting passes, and boilerplate are means, and having a model draft them is ordinary professional practice.

Human-first: the critique loop

1. Write the draft yourself, badly if necessary. A weak draft you wrote is more useful than a strong one you did not.
2. Ask the model to argue against it: name the weakest claim, the alternative you did not consider, the assumption you left unstated.
3. Revise from the critique — accepting some of it and rejecting the rest, on the record.
4. Log the exchange in prompt-log.md.

The failure mode here is asking "is this good?" A model asked that will tell you yes. Ask it to find the flaw and it has something to do.

AI-first: the verification loop

1. State what you want in one specific instruction, including the constraints that matter.
2. Read every line of the output before accepting it. Skimming generated files is how invented structure ends up in a portfolio.
3. Check anything factual against a source.
4. Log it, and record any error you caught in the mistakes section above.

Unverified output committed to your repository is your error, not the model's. The commit carries your name.

Revising the file

Re-read it whenever an engagement finishes, and whenever you notice yourself giving the same instruction twice in chat — the second time is the signal that it belongs in the file. A model can do the review with you:

Read my AGENTS.md and the last few things I committed to this repository.

1. Which instructions in the file does my recent work contradict?
2. Which instructions are vague enough that you could satisfy them either way?
   Quote each one and propose a specific replacement.
3. What did I have to tell you in chat this week that should have been in the file?
4. What can be deleted because it never changed your behavior?

Propose edits as a diff. Do not rewrite the file wholesale, and do not add
anything aspirational that my actual commits do not support.

Then read the diff and apply the parts you agree with. Accepting a wholesale rewrite gets you back to a generic file describing a generic student.

Related

• Portfolio repo standard — where AGENTS.md sits and what surrounds it
• Deliverable templates — the artifacts the boundaries above apply to
• AI Tools Lab — chat versus code tools, and which surfaces can read this file at all
• Git mechanics — .gitignore — the mechanical half of "never commit"