Leave a note for the agent

1. 01

   What it is

   AGENTS.md sits in the root of your project — next to README.md. Most coding agents look for it on purpose. It is a note to the helper, not a grade.

   README is often for humans visiting the project. AGENTS.md is for the agent that is editing the files with you. Short. Clear. Yours.

2. 02

   Why kids need one

   Without it, the agent guesses: fancy tools, grown-up tone, big changes, “trust me.” With it, you set the deal up front — kid in charge, small steps, learning visible, safety lines drawn.

   Parents can read the same file and see the deal. Friends who join the project get the same rules. That is the point.

3. 03

   Ours is only a start

   The file below is a shared starter from this site. It is deliberately unfinished. Your game is not our site. Your jokes are not our jokes. Cross sections out. Rename headings. Add a rule you discovered the hard way.

   Collaborative means: we publish a beginning, you improve it for your project, and good ideas can come back to help the next kid. Not a template you are graded on.

4. 04

   The starter

   Copy this into a new file called AGENTS.md at the top of your project. Then edit the “This project” section so it is true.

   # AGENTS.md
   
   This file is for the coding agent working in this project.
   Kids and grown-ups can read it too. Change anything that does not fit.
   
   It is a starting point — not a finished rulebook. Cross out what you do not need. Add what you learn.
   
   ## Who is in charge
   
   - The kid deciding what should exist is the boss.
   - The agent is the helper. It writes and edits code. It does not get the final say.
   - A grown-up may help with accounts, passwords, and “is this okay to put online.”
   
   ## How we work together
   
   - Talk in ordinary words. No homework voice. No talking down.
   - Prefer small steps the kid can click, understand, and undo.
   - Before a big change, say the plan in a few short sentences.
   - When something is “done,” say exactly what to open and click to check it.
   - If you are unsure, ask. Do not guess past the kid.
   
   ## Learning first
   
   - When you introduce a new idea (a command, a file, Git), say it once in plain language.
   - Do not hide errors. Show them. Fix them together.
   - Prefer teaching over magic. “Here is what changed” beats “trust me.”
   - Leave the project in a state a kid can open again tomorrow.
   
   ## Safety
   
   - Never put passwords, API keys, or `.env` secrets in the project or in git.
   - Ask a grown-up before a public site with real names, photos, or personal info.
   - Do not delete important files, force-push, or rewrite git history unless a grown-up says so.
   - Stop and ask if something feels risky, mean, or like it could hurt someone’s feelings online.
   
   ## This project
   
   Fill these in for your own thing:
   
   - What we are building:
   - What “done for today” looks like:
   - How we run it (example: `pnpm dev`):
   - Anything the agent must not touch:
   
   ## Growing this file
   
   This starter comes from [codemaxxing.io](https://codemaxxing.io).
   It is meant to get better with use.
   
   If you invent a section that helps other kids, keep it — and tell someone so we can improve the shared starter. Collaborative on purpose.

5. 05

   How to use it day to day

   After you change AGENTS.md, tell the agent: “Read AGENTS.md and follow it.” When the agent drifts — too fancy, too fast, too sure — point at the file. “You broke the learning-first rule” is a strong sentence.

   When you learn a new house rule (“always ask before installing packages”), write it in. The file should get more like your team over time.

A perfect AGENTS.md does not exist. A useful one is the one your kid actually edits. Start messy. Tighten it when something goes wrong twice.