psp_api/Agents.md

# AGENTS.md

## Stack

- NestJS
- Prisma
- TypeScript
- pnpm
- RTK enabled

---

# Core Rules

- Keep changes minimal.
- Do not touch unrelated files.
- Prefer existing patterns over new abstractions.
- Preserve API behavior unless requested otherwise.
- Prefer forward Prisma migrations.
- Never edit applied migrations in shared environments.

---

# EXECUTION RULES

- Keep responses short.
- Do not narrate thoughts.
- Do not explain obvious steps.
- Do not create plans for simple tasks.
- Prefer implementation over exploration.

Avoid:

- “I think…”
- “Let me check…”
- “I should inspect…”
- “I’m going to…”

---

# RTK Rules

Always prefer RTK commands.

Use:

- `rtk ls`
- `rtk grep`
- `rtk smart`
- `rtk read`
- `rtk git diff`
- `rtk git status`

Avoid raw:

- `cat`
- `grep`
- `rg`
- `git diff`
- recursive repository scans

---

# Reading Strategy

1. `rtk grep`
2. `rtk smart`
3. `rtk read`

Rules:

- Read only necessary files.
- Do not read sibling files unless needed.
- Do not reread unchanged files.
- Stop searching once target location is found.
- Edit quickly after locating target.

Avoid:

- opening entire modules
- multi-file chained reads
- large diff dumps
- exploratory scans

---

# Forbidden Paths

Do not inspect unless required:

- `node_modules/`
- `dist/`
- `coverage/`
- `.prisma/`
- `prisma/migrations/`

---

# Prisma Rules

- Use transactions for multi-step writes.
- Prefer explicit `select/include`.
- Normalize `Decimal` values with `Number(...)`.
- Keep migrations forward-safe.
- Use:
  - `pnpm prisma migrate dev --name <name>` for new local migrations
  - `pnpm prisma migrate deploy` for applying existing migrations

---

# NestJS Rules

- Keep layering:
  - controller
  - service
  - prisma/shared service

- Reuse shared services.
- Keep DTO validation strict.
- Avoid `any`.

---

# Validation

Typecheck before handoff:

```bash
pnpm -s tsc --noEmit
```

# INVESTIGATION LIMITS

For localized fixes:

- maximum 3 file reads before first edit
- maximum 1 related-file read unless required
- maximum 5 total file reads before implementation

Stop searching once the target service, controller, DTO, schema, or repository method is identified.

# TARGETED READ RULES

Do not read files larger than 300 lines unless required.

For known symbols:

1. rtk grep
2. rtk smart
3. read only the relevant section

Avoid opening entire services, modules, or controllers for localized changes.

Prefer symbol-level inspection.

# REVIEW MODE

During reviews:

- inspect changed files only
- avoid repository-wide searches
- avoid architecture exploration
- avoid reading unrelated modules

Review only code affected by the diff.

# HARD TOKEN LIMITS

For localized fixes:

- Never read more than 5 files before the first edit.
- Never read a file larger than 300 lines unless the target symbol cannot be isolated.
- Never open an entire service, controller, or module when a symbol-level read is possible.
- Never reread a file already summarized by `rtk smart` unless implementation details are required.

When a file exceeds 300 lines:

1. rtk grep
2. rtk smart
3. read only the required section

Avoid full-file reads.