Agent instructions
What Fragua writes into a new app so every agent run starts oriented.
When Fragua scaffolds a new app (the greenfield path), it commits one small file of agent instructions before the first push. It's there so every later run — yours or a teammate's — starts knowing the basics of the app instead of rediscovering them each time.
What gets created
Two files, committed together. One is the real document; the other is a pointer to it, so every coding agent finds the same instructions where it expects them.
.claude/CLAUDE.md
The instructions themselves. Claude Code reads this file automatically at the start of a run, with no setup on your part.
AGENTS.md
A symlink at the repo root pointing to the file above. Other coding agents look for AGENTS.md there, so they read the same instructions — one source, no duplicate to keep in sync.
What's inside
A deliberately short starting point — the app's name, how to run it, and room for you to grow it. Nothing you have to maintain on day one.
bin/dev
Start the development server on the app's assigned port.
bin/rails server
Start the server without the process manager.
bin/rails test
Run the test suite.
bin/setup
Install dependencies, prepare the database, and get a fresh checkout running.
-
The app's development port is fixed for you, so it never collides with another app you're running side by side.
-
An empty Gotchas section is left for you to fill in — the place to record surprises as you hit them. The next guide covers what's worth adding.
Why two files
Claude Code loads the .claude/CLAUDE.md file on its own, so the instructions reach the agent without any configuration. Other tools — like Codex or Cursor — look for an AGENTS.md at the repository root instead. The symlink bridges the two: both read the exact same content, and you only ever edit one file.
A few lines of project context measurably improve every run.