NINI
132 lines
2.3 KiB
Markdown
132 lines
2.3 KiB
Markdown
# 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
|
|
|
|
```markdown
|
|
## 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
|
|
|
|
```markdown
|
|
## 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
|
|
|
|
```markdown
|
|
## 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
|
|
|
|
```markdown
|
|
## Testing
|
|
|
|
- API endpoint tests use `tests/helpers/request.ts`; avoid ad hoc server setup.
|
|
```
|
|
|
|
Why: establishes known-good patterns.
|
|
|
|
### Configuration Quirks
|
|
|
|
```markdown
|
|
## 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:
|
|
|
|
```markdown
|
|
The `UserService` class handles user operations.
|
|
```
|
|
|
|
The class name already says that.
|
|
|
|
### Generic Best Practices
|
|
|
|
Bad:
|
|
|
|
```markdown
|
|
Always write tests for new features.
|
|
Use meaningful variable names.
|
|
```
|
|
|
|
Add only project-specific rules.
|
|
|
|
### One-Off Fixes
|
|
|
|
Bad:
|
|
|
|
```markdown
|
|
We fixed a bug where the login button did not work.
|
|
```
|
|
|
|
Unless the lesson is durable, leave it out.
|
|
|
|
### Verbose Explanations
|
|
|
|
Bad:
|
|
|
|
```markdown
|
|
The authentication system uses JWT tokens. JWT means JSON Web Token...
|
|
```
|
|
|
|
Good:
|
|
|
|
```markdown
|
|
Auth: JWT HS256 tokens in `Authorization: Bearer <token>`.
|
|
```
|
|
|
|
## Diff Format
|
|
|
|
For each suggested change:
|
|
|
|
```markdown
|
|
### 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.
|