# Instruction files: example scenario

Stop agents guessing commands and hand-editing migrations in ticket-service with a project instruction file and a directory-scoped one for src/db/.

Source: https://ai-sw-factory.mellicci.dev/fundamentals/instruction-files/example-scenario

## Scenario

In `ticket-service`, four developers use four different coding agents. Each agent guesses: one runs `npm install` in a pnpm project, another calls a test command that does not exist, a third edits a file in `src/db/migrations/` by hand and breaks the migration history. Every developer corrects these mistakes in every session, and the corrections are never written down.

This page shows one way to fix that: a project-level instruction file at the repo root and a second file scoped to `src/db/`.

## Before → after

| | Before | After |
|---|---|---|
| Commands | The agent guesses `npm` or an invented test script | It runs `pnpm install` and `pnpm test` from the first prompt |
| Risk | Migrations are edited by hand and caught in review | The boundary says to generate them with `pnpm db:generate` |
| Consistency | Each developer repeats the same corrections | The corrections are written once and reviewed in pull requests |
| Time | Every session starts with re-teaching | Every agent starts from the same facts |

## Design

**Diagram:** The project file is always loaded; the directory file joins only for work under src/db/ — when exactly depends on the agent.

- ticket-service repo:
  - Project file — commands, layout, boundary
  - src/routes/ — no extra file
  - src/db/:
    - Directory file — schema and migration rules
    - migrations/ — generated, never hand-edited
- → loaded into
- Context window:
  - Project file text — every session
  - Directory file text — only under src/db/

Generic project file at the repo root (file name depends on your agent):

```markdown
# ticket-service
Fastify + TypeScript API on PostgreSQL (Drizzle). Package manager: pnpm.
## Commands
- `pnpm install`, `pnpm dev`, `pnpm test` (Vitest), `pnpm lint`
- `pnpm db:generate` (new migration), `pnpm db:migrate` (apply)
## Layout
- `src/routes/` HTTP handlers · `src/db/` schema and migrations
- `test/` Vitest specs · `docs/` API notes
## Conventions
- Named exports only; every route change needs a test in `test/`.
- Never hand-edit `src/db/migrations/`; generate them with `pnpm db:generate`.
```

Generic directory file in `src/db/`:

```markdown
# Database code
- Change `schema.ts`, then run `pnpm db:generate`.
- Review the generated SQL before `pnpm db:migrate`.
- Never edit or rename files in `migrations/`.
```

File names differ per agent; the agent pages give the exact names.

## What happens at runtime

<steps>

<step title="Session starts">

The harness finds the project file at the repo root.

</step>

<step title="Project file enters the context">

Its text sits ahead of your first prompt, so "run the tests" becomes `pnpm test`.

</step>

<step title="Agent works in src/db/">

You ask for a `priority` column on tickets, and the agent opens `schema.ts`.

</step>

<step title="Directory file joins">

The harness adds the `src/db/` guidance to the context. Agents differ on when: as soon as the agent reads files there, only if you start the agent in that directory, or when a file matches a path pattern. Routes work never pays for it.

</step>

<step title="Agent generates instead of editing">

The model edits `schema.ts`, runs `pnpm db:generate` and leaves existing migrations alone.

</step>

</steps>

## What can go wrong

| Failure | How you notice | What to do |
|---|---|---|
| The file is a request, not a guarantee | The agent still edits a migration | Enforce it with a [hook](https://ai-sw-factory.mellicci.dev/fundamentals/hooks) that blocks the write |
| Commands go stale | A renamed script fails in early agent runs | Update the file in the same pull request that changes scripts |
| The file grows too long and costs context | Slow, costly turns; rules get ignored | Prune what the agent already does; move procedures to [skills](https://ai-sw-factory.mellicci.dev/fundamentals/skills) |
| A secret ends up in the file | A token or password shows up in the diff or git history | Keep secrets out: the file is committed and sent to the model every session; see the [security model](https://ai-sw-factory.mellicci.dev/fundamentals/security-model) |
| Files conflict across scopes | The agent follows one rule and breaks another | Keep each rule in one place; check your agent's precedence rules |