> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fermata.run/llms.txt
> Use this file to discover all available pages before exploring further.

# Project instructions

> Standing context every agent in a project receives, on top of everything your Claude setup already provides.

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.

<Note>
  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.
</Note>

## 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.