Patterns / Context

Project rules file

Keep stable project knowledge in one versioned file the agent reads every session.

The problem

Every new session starts from zero. You end up retyping the same facts (how to run tests, which directories matter, the conventions you care about), or worse, you forget and the agent invents its own.

The pattern

Keep a short rules file in the repository root that your agent tooling loads automatically (many tools support a convention such as an agents or rules markdown file) or that you paste in at the start. Keep it versioned with the code so it stays in sync.

Put in it only what is stable and useful in most tasks: commands, layout, conventions, gotchas, and the hard constraints. Keep it short; every line costs context in every session. When the agent repeats a mistake, add one line that would have prevented it.

Template

# Project rules

## What this is
<One paragraph: purpose, main users, current stage.>

## Commands
- Install: `<cmd>`
- Run locally: `<cmd>`
- Test (all): `<cmd>`   Test (one file): `<cmd> <path>`
- Lint / typecheck: `<cmd>`

## Layout
- `<dir>/` - <what lives here>
- `<dir>/` - <what lives here>

## Conventions
- <naming, error handling, logging, formatting rules>
- Prefer <X> over <Y> because <reason>.

## Gotchas
- <non-obvious thing that has bitten us before>

## Hard constraints
- Never <dangerous action>.
- Ask before <costly or irreversible action>.

## Definition of done
- Tests and lint pass; final report lists what was verified.

When not to use it

• For task-specific details. Those belong in the task brief; putting them here bloats every future session.
• As a dumping ground. If the file grows past what you would read yourself, prune it.