Write repository instructions for AI agents: commands, boundaries and local conventions

A worked example: where the task becomes difficult

A fictional monorepo has a dashboard package and a worker package. Running a root development command starts the wrong application for a dashboard bug. The agent also mistakes generated client files for editable source. Repository instructions should identify package-specific commands and the code-generation boundary, with a small example of how to verify a UI change. They should not promise commands that have never been run.

Decisions to make before implementation

Separate durable project conventions from one-off task constraints. Explain the precedence of root and package instructions where the tool supports it. Include commands with required environment prerequisites, but never store secret values in instruction files. Name actions requiring separate authorization, such as production migrations or external notifications. Avoid a giant rulebook whose contradictory exceptions prevent ordinary work.

A practical sequence for the work

Use the sequence below as a task boundary, not as a claim that the example has been executed. Work with approved inputs and the project’s actual architecture. If a required integration or permission is unavailable, keep that stage visibly incomplete rather than generating a plausible substitute result.

• Inspect manifests and confirm the relevant run and check commands.
• Document source directories, generated output and package ownership.
• Add concise conventions and explicit boundaries for consequential actions.
• Exercise the instructions with one controlled task and correct misleading guidance.

A detailed brief you can adapt for your agent

Replace the illustrative context with your approved facts and controlled inputs. Keep the stated boundaries when adapting the brief. The expected deliverable matters more than a particular tool name: ask for an explanation grounded in the inspected material and evidence for the requested outcome.

Draft repository instructions from the inspected package manifests and current conventions. Include dashboard and worker run commands, meaningful checks and generated-file boundaries. Mark unverified commands explicitly. Do not include secret values or grant production deployment authority. Keep task-specific requirements outside the durable project rules.

Failure modes that an attractive preview can hide

Copied instruction templates can mention unavailable tools, nonexistent test suites or another team’s deployment process. That sends the agent into avoidable retries. Keep verified commands separate from proposed future commands. Instructions can also become stale after a package move; assign maintenance responsibility and review them alongside architecture changes rather than treating them as permanent facts.

Technical references: GitHub: getting useful results from coding tasks

Acceptance checks and the evidence to retain

Provide the instruction file, the commands actually checked and a list of environment prerequisites. Another contributor should be able to distinguish project conventions from assumptions.

Specific answers

Common questions