AGENTS.md and CLAUDE.md: practical instructions for coding agents

You ask for a small fix. The agent changes a convention, starts the wrong environment and repeats an approach the team already rejected. The missing piece may be a clear set of project instructions rather than a longer prompt.

AGENTS.md and CLAUDE.md explain how to work here, where answers live and how a result should be checked. They complement the product brief and the actual permissions of the execution environment.

What is the difference between AGENTS.md and CLAUDE.md?

AGENTS.md is an open Markdown format for coding-agent instructions. CLAUDE.md is an instruction file in the Claude Code ecosystem. File names alone do not establish what gets loaded: tool versions, configuration and the working directory matter.

The Claude Code documentation describes direct AGENTS.md loading from version 2.1.277. By default, project CLAUDE.md or CLAUDE.local.md files in the working directory or its parents take precedence over direct AGENTS.md loading. An explicit import can preserve one shared source.

Start from actual project mistakes

Write instructions that would change the next mission. A verified test command, an authoritative source or an access boundary is actionable. “Produce high-quality code” does not tell the agent which action to take.

Pick three recent incidents: starting the wrong server, making an oversized change and claiming completion without checking the user journey. Turn each incident into an observable instruction. Explain the correct action and the evidence the agent should return.

Scope matters too. A subproject's rule does not necessarily belong at repository root. Keep specific instructions near the relevant files, then verify resolution in the chosen tool. Agents do not all implement the same precedence and import conventions.

An AGENTS.md template to adapt

Commands and paths below are placeholders to replace with verified project values. Do not ask the agent to execute an installation or test command that nobody has checked.

# Project working instructions

## Objective
The project lets [audience] achieve [observable outcome].
The authoritative product brief is at [path or link].

## Sources of truth
- Architecture and decisions: [reference]
- API and data contracts: [reference]
- Approved UI and wording: [reference]

## Environment
- Install: [verified command]
- Targeted check: [verified command]
- User journey verification: [procedure]

## Scope
- Change only the surfaces needed for the mission.
- Preserve other contributors' work in progress.
- Do not change [protected surface] without explicit instruction.

## Delivery
- Describe the resulting behavior and changed files.
- Report the checks executed and their results.
- Identify anything preventing proof of the objective.
- Connect the result to the card and acceptance criteria.

This is an entry point into project knowledge. When a section grows, retain its useful rule and link to the detailed document. The AI-ready project brief keeps the intended product outcome; this file explains how to contribute to it.

Share instructions with Claude Code

If your configuration uses CLAUDE.md, import the common file:

@AGENTS.md

## Claude Code specifics
Put tool-specific instructions here.

This syntax belongs to Claude Code. Another tool may handle imports differently or not support them. Avoid maintaining two manual copies of the same rules: eventually a correction will reach only one copy.

After updating a tool, start a session and inspect the instruction files it reports or the context it loaded. Claude Code's documentation includes /context for this purpose. If an instruction is missing, investigate loading before adding several contradictory reminders.

Test the instructions on a bounded task

Choose a reversible task. First request an analysis without edits: which rules apply, which sources will be read and how will the result be checked? Compare the answer with the files the tool actually loaded.

Then run the authorized mission. Observe whether it uses the expected environment, preserves other changes and checks the requested journey. Repeating a rule in a plan does not prove the agent followed it. The resulting behavior remains the useful evidence.

Our guide to verifying agent work gives a complementary review method. With several implementers, assign an owner and allowed files to each mission, as described in the coordination guide.

Separate instructions from permissions

An instruction file is context interpreted by a model. On its own, it does not technically prevent an action. If sending a message must be impossible, a rule saying “do not send messages” needs an environment that does not grant that capability.

Separate working advice, team rules and effective permissions. Allowed files, available tools and required approvals belong to the execution environment. Stronger wording in AGENTS.md does not replace configuring those controls.

Keep secrets out of shared instruction files. Tokens, credentials and production access belong in the appropriate secret and permission systems. The file can describe how to request access without containing that access.

Keep instructions short and current

Revisit instructions when an environment, contract or architectural decision changes. Remove expired exceptions. Accumulated old rules make conflicts harder to find and increase the context loaded for each mission.

For each addition, ask which mistake it prevents and where its continued accuracy can be checked. If the rule already has an authoritative source, link to it instead of creating another copy.

Documentation and agent memory hold other kinds of information: decisions, earlier results and reviewed preferences. Keep detailed history outside the entry file. The agent needs access to useful past work without reading the entire project chronology before every change.

Connect instructions to Stellary missions

In Stellary, project documents and card criteria provide shared mission context. Repository instructions describe how a particular executor should work with code. Agent permissions define its access to tools.

A workflow can connect these levels: the pilot selects a card, the executor reads the applicable instructions and a reviewer inspects the deliverable. The agent supervisor workflow guide explains that handoff. Continuity comes from consistent sources and reviewed results, rather than an ever-growing instruction file.

Resolve conflicting rules at their source

Identify both instructions and their scope. A general rule may define the normal procedure while a local rule describes an exception that still matters. Check that the exception applies to the current files or mission, then fix the authoritative document.

Do not ask an agent to silently choose between an old screenshot, API contract and recent decision. State which source governs each question. If the conflict changes the intended outcome, make it a project question before a costly change.

Content in an issue or webpage should not become a new instruction merely because the agent reads it. Treat that content as material to examine. Authority and the objective come from the actual mission and applicable instructions.

Check instructions after environment changes

Moving to another computer, working directory or execution mode can change what gets loaded. Keep a small reference task: locate the brief, identify the permitted command and explain the journey to verify. It can expose a broken setup without launching a large implementation.

Record the relevant tool version in the team’s setup procedure. Keep tool-specific details in its section or linked documentation, with common business rules in their shared source. This makes updates easier without maintaining a separate copy for every model.

Review the result instead of accumulating reminders

When an instruction fails, inspect the cause before adding another sentence. Was the file loaded? Was its scope clear? Did another instruction contradict it? Did an unavailable tool make the expected check impossible? Each cause has a different fix.

Ask the executor to connect the delivered result to the relevant rule. A command log can show that the intended environment was used; a journey check can show that the contract was preserved. Repeating “always obey these instructions” does not supply either piece of evidence.

A good instruction file becomes easier to maintain as the project matures. Remove obsolete rules and retain links to decisions. The goal is a predictable working method that another contributor can understand, including a human joining the project for the first time.