Write a project instruction file for a coding agent

Is it the right skill?

Before you start

• Commands that build and test the project from a clean checkout.
• Agreement on which directories and actions are off limits.

Steps

Do not move on until the checkpoint holds.

1. Write commands verbatim

   List the exact install, build, test and lint commands, copied from a run that worked.

   Checkpoint Each command succeeds when pasted into a fresh terminal.

2. State boundaries

   Name directories not to edit, actions that need approval (dependencies, migrations, network) and the rule that secrets never go into files.

   Checkpoint Every boundary is phrased as a concrete rule, not a preference.

3. Show conventions with examples

   Point to one existing file as the model for style, naming and tests.

   Checkpoint Each convention links to a real file in the repository.

4. Define done

   List the checks that must pass and what the agent should report at the end.

   Checkpoint A reviewer could tell from the report whether the task is finished.

5. Run a trial task

   Give an agent a small real task with only the file as guidance, and note every place it went wrong.

   Checkpoint Each mistake leads to an edit of the file, or a decision that it was not the file's fault.

What can go wrong

• Security The file is read by tools and people. Never include tokens, internal hostnames or customer data.
• Accuracy Out-of-date commands are worse than none. Re-run them whenever the build changes.

Related entries

• FM-08 Have a coding agent implement against tests you wrote first
• FM-09 Review a pull request with an agent that cannot change anything

Revision history