Writing for Agents

The main problem is that the important rules are hard to spot among filler. Here's a rewrite:

# Project Guidelines

Next.js 15 (App Router) + TypeScript, managed with **pnpm**. Scripts are in `package.json`.

## Rules

- Run every package and script command through `pnpm` (`pnpm add`, `pnpm dlx`, `pnpm <script>`). The lockfile is `pnpm-lock.yaml`, and running another package manager corrupts it.
- Use precise types everywhere. For data whose shape you don't know yet, use `unknown` and narrow it with type guards or a schema. Never use `any`.
- Keep React components presentational. Put business logic in <!-- TODO: e.g. `src/lib/` or `src/server/` --> and call it from the component.
- Style with Tailwind utility classes only.

## Database (Prisma + PostgreSQL)

After any edit to `prisma/schema.prisma`, run both commands, in this order:

1. `pnpm prisma migrate dev --name <descriptive_name>`
2. `pnpm prisma generate`

If you skip step 2, the generated types go stale and the build fails in ways that are hard to trace back.

## Testing

Vitest. Put each test next to its source file as `<name>.test.ts`.

## Done means

You're finished only when both commands pass with zero errors on your final change:

- `pnpm lint`
- `pnpm test`

What I changed and why:

1. Cut lines that don't change behavior. "Be careful and thorough" and "write good code that follows best practices" are things the agent already tries to do. They make the file longer and draw attention away from the rules that matter.
2. Gave each rule one home. "Run tests" appeared twice and "use pnpm" was said twice in one bullet. When an instruction is repeated, it's hard to tell how important it is compared with the rest. Lint and test now live in a single Done means section at the end, where the agent checks whether it's finished.
3. Said what to do, not just what to avoid. Rules like "Don't use npm or yarn", "Never use any", and "Don't write CSS / inline / styled-components" put the banned thing front and center. Each rule now names what to use instead (pnpm, unknown + narrowing, Tailwind classes). I kept "Never use any" as a hard limit, paired with the alternative.
4. Added the reasons agents can't figure out on their own. The lockfile damage and the stale Prisma types are why those rules exist. A rule that comes with its reason is less likely to be dropped as optional.
5. Turned the Prisma steps into a numbered list instead of a paragraph ending in "Don't forget!!".
6. Made "finished" checkable. "Run lint and test" became "both pass with zero errors". Before, an agent could run the tests, see failures, and still stop.

One thing for you to fill in: "Don't put business logic in components" probably gets ignored because the agent doesn't know where that logic should go. Replace the TODO with your real directory, such as src/lib/ or server actions in app/**/actions.ts.

Optional: if agents still use npm or skip lint, put it in a hook instead of the doc. A PreToolUse hook can block npm/yarn commands, and a Stop hook can run pnpm lint && pnpm test. I can set either one up with /update-config if you want.