Rules and instructions

You can tell Dev and your agents how to behave in a few places, and each one reaches a different audience. Your team's engineering values go to everyone. The mechanics of building and shipping go to every agent on the project, never to Dev. Your own machine setup goes to your agents only, and how you like replies written follows you everywhere. Setting these once means nobody has to repeat them at the start of every session, and every agent works to the same rules whoever is driving it.

Where you can set rules

Project settings are available on desktop. Everyone on a project can read its Principles and Agent execution rules; only Maintainers can change them there.

Set your project's Principles

Principles describe how your team works: your quality bar, when to use a platform instead of building your own, what shipping something properly means here. Dev reads them in every session in the project, and every agent on the project receives them too.

To add a principle, go to Project settings → Agent rules, find Project principles and press Add a rule. Write one principle under The rule, say why under Why (optional), choose a Class, and press Add rule. Each principle saves on its own and shows who added it and when, so two people can add principles without overwriting each other. To remove one, press its bin icon (Remove this rule).

Principles a project had before they were kept one at a time appear as a single entry marked Imported, author unknown. To split it up, add the principles you want to keep as separate entries, then remove the imported one.

Keep Principles to things that apply to everyone. Step-by-step build mechanics belong in Agent execution rules, which Dev doesn't need, and decisions about how the system is built are better kept as memories, where they can be searched, discussed and replaced when they change.

Add Agent execution rules

Agent execution rules are the mechanics your agents follow on this project: checks to run before pushing, commit and branch conventions, files and paths they must never touch. Dev doesn't see them, because Dev doesn't change code.

On Project settings → Agent rules, find Agent execution rules and press Add a rule:

1. Under The rule, write one rule, stated plainly. Add another rule for the next one rather than combining them.
2. Under Why (optional), say why the rule exists. This helps teammates understand why the rule exists. Agents receive the rule itself, not this separate explanation.
3. Choose a Class:
   • Safety: shared-repository safety, such as branch protection, force-pushing and secrets. Agents are told not to work around these.
   • Mechanics: how to build and ship here.
   • Style: preferences and tone, as guidance rather than a hard constraint.
4. Press Add rule.

Each rule saves on its own and shows its class, who added it and when, so two people can add rules without overwriting each other. To remove one, press its bin icon (Remove this rule).

The same page holds your other agent settings, such as Protected paths, Auto-push and Auto-merge. See Working with your agents.

Principles and Agent execution rules each allow 50,000 characters across their own list of rules. The reason for an individual rule can be up to 10,000 characters. If an edit would exceed a limit, nothing is cut or saved; shorten the text and try again.

Bring in rules from a CLAUDE.md or AGENTS.md file

If your repository already has a rules file for an agent, such as CLAUDE.md, AGENTS.md or .cursorrules, you don't need to retype it. Ask a connected agent to import your rules from it:

Import our rules from CLAUDE.md into DevSpec.

The agent reads the file and sorts each part into the right place: team rules, Principles, your own personal agent rules, or decisions worth recording as memories. It leaves behind anything DevSpec already learns from your code, such as directory layouts and commands. It shows you the plan first, and writes only what you agree to. What lands straight away and what waits for a Maintainer depends on your project role (see Rule changes waiting for a Maintainer).

Do I need a DevSpec rules file?

No. DevSpec supplies guidance through its plugins, and a plugin is required for each agent. Pi, Claude Code and Antigravity CLI need no repository file.

If your agent's plugin doesn't yet bring DevSpec's guidance into every conversation, the last step of connecting, headed Paste this into and your tool's name, offers a repository reminder for that tool. You can also find it in the connection instructions on Agent setup. It points the agent to current guidance instead of copying workflow rules that can go out of date.

Use Copy reminder and add it to the named file (or your client’s project-instructions feature). Keep your other instructions; replace an older Working with DevSpec section rather than adding it twice.

Set your personal agent rules

Personal agent rules are for things about your own machine and tools that your agents should know: tools you have installed, local ports or services, your preferred package manager. They apply to your agents only, on every project, and never to anyone else's. Dev doesn't see them.

To set them, open Agent setup, find Personal agent rules, write in Rules for agents on your machine, and press Save. You have up to 10,000 characters.

Your agents pick up changes while they are running; you do not need to restart them. Keep team rules out of here: a rule every agent on the project should follow belongs in Agent execution rules, where the whole team can see it.

Choose how Dev and your agents reply to you

Response style sets the tone and length of the replies you read. It belongs to you, not to the project, so it follows your messages to Dev and to your connected agents alike. It shapes the reply you read, never what gets written into a task, a brief or a document.

In Settings → Replies & voice:

• Conversational replies asks for short, direct answers in a spoken, conversational way, taking one thing at a time when there's a lot to cover. It's off until you turn it on, and the page shows the exact wording.
• Focus on the product, not the code asks for explanations in terms of what people can do and the choices you need to make, without code-level detail unless you ask. It's off until you turn it on; View instructions shows the exact wording.
• Both switches are also in Message settings next to the message box in a session.
• Anything else about how you want to be answered? takes up to 10,000 characters of your own preferences, for example "Assume I'm a senior engineer" or "Give me the trade-off before the recommendation". Press Save.

See Your settings for the rest of the page.

Rule changes waiting for a Maintainer

Changing team rules affects every agent on the project, including agents belonging to people who aren't in the conversation, so some changes wait for a Maintainer:

• A Contributor or Reviewed Contributor can propose a new rule, for example by asking their agent to add one. The rule waits for a Maintainer instead of taking effect. Changing or removing an existing rule needs a Maintainer.
• A rule proposed during an automation waits for a Maintainer, whatever role the automation runs for.
• A Viewer can't change team rules.

A waiting rule isn't in effect: no agent sees it until a Maintainer accepts it. Waiting rules appear on Project settings → Agent rules, above the settings, under Rule changes waiting on you for Maintainers (everyone else sees Rule changes awaiting a maintainer), with who proposed it and why. They also appear in Review, under Waiting on you for the people who can decide and All waiting for the wider project. A Maintainer presses Accept to put the rule into effect, or Decline to drop it. See Review.

When rules overlap

Each set of rules has its own audience, so most overlaps never happen: Dev reads Principles and your Response style; an agent reads Principles, Agent execution rules, your personal agent rules and your Response style.

Where an agent's rules do disagree, team rules in the Safety class always win over anyone's personal agent rules, and agents are told not to work around them. For anything else, keep one rule in one place: if a team rule and a personal rule say different things, move or remove one of them so your agents aren't left to choose.