NINI
2.3 KiB
2.3 KiB
AGENTS.md Update Guidelines
Core Principle
Only add information that will genuinely help future Codex sessions. The context window is precious; every line must earn its place.
What To Add
Commands and Workflows Discovered
## Commands
`npm run build` - Production build.
`npm run lint` - ESLint check required before handoff.
Why: saves future sessions from rediscovering commands.
Gotchas and Non-Obvious Patterns
## Gotchas
- Tests must run sequentially because they share a local database.
- Regenerate API clients with `npm run codegen` after editing OpenAPI files.
Why: prevents repeated debugging.
Package Relationships
## Architecture
- `packages/api` owns route handlers; `packages/ui` must call it through the shared client.
Why: captures relationships that are not obvious from filenames.
Testing Approaches That Worked
## Testing
- API endpoint tests use `tests/helpers/request.ts`; avoid ad hoc server setup.
Why: establishes known-good patterns.
Configuration Quirks
## Environment
- `NEXT_PUBLIC_*` variables must be set at build time.
Why: environment details often waste time when omitted.
What Not To Add
Obvious Code Info
Bad:
The `UserService` class handles user operations.
The class name already says that.
Generic Best Practices
Bad:
Always write tests for new features.
Use meaningful variable names.
Add only project-specific rules.
One-Off Fixes
Bad:
We fixed a bug where the login button did not work.
Unless the lesson is durable, leave it out.
Verbose Explanations
Bad:
The authentication system uses JWT tokens. JWT means JSON Web Token...
Good:
Auth: JWT HS256 tokens in `Authorization: Bearer <token>`.
Diff Format
For each suggested change:
### Update: ./AGENTS.md
**Why:** The build command exists but was missing from project instructions.
```diff
+## Commands
+
+`npm run build` - Production build.
## Validation Checklist
- Each addition is project-specific.
- No generic advice or obvious info.
- Commands are verified against the repo.
- File paths are accurate.
- The wording is concise.
- A new Codex session would benefit from the line.