Skip to main content
Project instructions are a block of text you write once per project. Every coding agent Fermata starts in that project receives it, on every run, without you pasting it into a prompt again. The spec interview and the code-review pass (an Edge feature) do not: they are Fermata’s own planning agents, not agents touching your code. Use it for the things you would otherwise repeat in every session: the conventions that are not obvious from the code, the commands that actually build and test, the directories to leave alone, the review standard you hold work to.

​
Where to write them

Two places, both editing the same document:
  • Settings → Project → Project Instructions (⌘,)
  • The “Project Pulse” inspector on Home, where the card offers Add Instructions or Edit
Save in one and the other shows the change immediately.

​
How they reach the agent

The text is stored with the project, at .fermata/fermata-agents.md inside the project root, and appended to the agent’s system prompt when a session spawns. Three consequences worth knowing:
  • It is read fresh at spawn. Edit the instructions and the next agent picks them up. Sessions already running keep the copy they started with.
  • It follows the project, not the worktree. An agent working in a piece’s worktree still gets the project’s instructions, because they resolve from the project root.
  • It is a file, so it is yours. Commit it if you want it shared, or leave it out of git if it is personal to your checkout.
There is a 64 KB cap, and the editor shows your byte count against it. Oversized instructions are truncated on a character boundary and the agent is told they were clipped, rather than the spawn failing. Keep it to the standing rules; it is not a place for a design document.

​
This stacks with your Claude setup

Fermata runs your own Claude, so everything your Claude setup already does still happens: your CLAUDE.md files, your skills, your subagents, your MCP servers, your output styles, your permissions. Fermata does not replace any of it. Project instructions are an additional layer that Fermata contributes, on top of what the CLI already loads. If a rule belongs to the repository and everyone working in it, CLAUDE.md is usually the better home. If it is about how you want Fermata’s agents to behave in this project, put it here.

​
What to put in it

Good candidates:
  • Build, test, and lint commands that are not discoverable from the repo
  • Directories or generated files agents should never edit
  • Conventions a reader would not infer: naming, error handling, logging
  • The definition of done you expect before work is offered for review
  • Things that have burned you before, written as a rule
Poor candidates:
  • Anything already stated in CLAUDE.md, which the CLI loads anyway
  • Detail specific to a single piece, which belongs in that piece’s spec
  • Long architectural prose. Agents read the code; give them the rules the code does not state.