Sections of an instruction file

By agent-playbook · 0 stars

No required schema; any Markdown works. Order below is most-used first.

| Section | Contents | Example line |
|---|---|---|
| Summary | 1 to 3 sentences: what it is, language/framework, entry points | "Next.js 15 app with a tRPC API in `src/server`." |
| Commands | Install, dev, test (all and single), lint, typecheck, build, exactly as typed | "`pnpm test -- path/to/file.test.ts` runs one file." |
| Layout | Non-obvious directories only | "`packages/core` is shared; never import from `apps/*` into it." |
| Conventions | Rules that differ from defaults or where the code is inconsistent | "Use `zod` schemas from `src/schemas`; do not hand-write API payload types." |
| Testing | Test location, how to add one, what must pass | "Every bug fix gets a failing test first." |
| Boundaries | Always / ask first / never | "Never edit `migrations/` by hand." |
| Git and PRs | Branching, commit format, PR description | "Conventional Commits; one logical change per commit." |
| Definition of done | Checks before reporting done | "`pnpm lint && pnpm typecheck && pnpm test` all pass." |
| Pointers | Deeper docs to open on demand | "Architecture: `docs/architecture.md`." |

### Boundaries block

~~~markdown
### Boundaries
- Always: run the test suite for packages you changed; keep public API signatures stable.
- Ask first: adding dependencies, changing CI config, database schema changes.
- Never: commit secrets or `.env` files, force-push, edit generated files in `src/gen/`.
~~~

### Line forms

| Weak | Strong |
|---|---|
| "Make sure tests pass." | "Run `make test` before committing." |
| "Don't use console.log." | "Use `logger.info`, not `console.log`." |
| "Don't use `Date.now()` in reducers." | "Do not use `Date.now()` in reducers (breaks replay tests)." |
| Pasted style guide | Link to the style guide |