Workflow
Starting a project: scaffold it so the tools — and the agents — know the rules.
A new project is more than an empty folder. A minute of setup gives every AI agent the project's conventions, pins the right tool versions, and starts its Git history — so the work goes smoothly from the first commit instead of the tenth.
new-project name scaffold the structureAGENTS.md write the project's rulesmise use … pin tool versionsgit init start historygh repo create put it on GitHubclaude start building#Why a project needs a guide
An AI agent is only as good as what it knows about your project. Tell it nothing and it guesses your stack, your test command, your conventions. Write them down once — in a file the agent reads automatically — and it follows them every time, the same way a new teammate would read the README. That file is AGENTS.md; tool-specific files should point back to it.
#Scaffold it — new-project
This setup ships a small command that lays the structure down for you. Point it at a folder:
$ new-project my-app
$ cd my-appIt creates a single source of truth for all your AI tooling — a .agents/ folder holding your rules, agents, skills, and commands — and then points vendor directories at it with symlinks where those tools support discovery. The important bit is that you edit one canonical tree instead of copying rules into several tool-specific folders:
my-app/
AGENTS.md # the shared project guide (you edit this)
CLAUDE.md # tiny adapter: @AGENTS.md + Claude-only notes
.agents/ # the canonical source of truth
rules/ agents/ skills/ commands/
.claude/ .codex/ # symlinks → .agents/ (every tool, one source)
.vscode/ # format-on-save, trim whitespace, LF endings
.gitignore # ignores .env and local override filesThe point of the symlinks: you write a rule, command, or skill once in .agents/, then tool-specific folders point back to it. No copy-paste, no keeping two files in sync.
#Fill in AGENTS.md
The scaffold leaves a skeleton. Replace it with the handful of things an agent (or a new contributor) genuinely needs — and delete any section you don't have a real answer for, because empty scaffolding just wastes the agent's attention:
| Stack | Language + version, key frameworks, and anything the project deliberately avoids |
| Commands | How to build, test, and lint — the exact commands |
| Conventions | Naming, file layout, and rules the code can't show on its own (error handling, data access) |
| Workflow | Branch and commit conventions specific to this repo |
A short, true AGENTS.md beats a long aspirational one. Two sentences the agent actually follows are worth more than a page it has to wade through. You can even ask claude to draft it: "read this project and write a starter AGENTS.md."
#Pin the tools — mise & direnv
So the project uses the same runtimes on every machine (and every agent), pin them with mise. Anyone who cds in gets exactly these versions:
$ mise use node@22 python@3.13 # writes mise.toml, installs them
$ echo 'export API_URL=http://localhost:3000' > .envrc
$ direnv allow # load .envrc whenever you're in this folderdirenv loads that .envrc automatically when you enter the folder and unloads it when you leave — so project settings never leak into the rest of your shell. (Keep real secrets out of Git; .env is already in the scaffold's .gitignore.)
#Start the history
Make it a Git repo and put it on GitHub — one commit, then it's real:
$ git init && git add -A && git commit -m "chore: scaffold project"
$ gh repo create my-app --private --source=. --push#Then build
That's the setup done. Open the folder in a tmux session, start an agent, and go — it'll read your AGENTS.md and work to your rules. A separate kind of project, a knowledge wiki, has its own scaffolder (new-wiki) for turning sources into a durable, AI-maintained reference.
#Going deeper
- AGENTS.md — the open convention for the project-instructions file, used across AI coding tools.