161 lines
5.8 KiB
Markdown
161 lines
5.8 KiB
Markdown
# AGENTS.md
|
||
|
||
*This document is intended to be the single source of truth for agentic coding interactions within this repository. Keep it updated as tooling or conventions evolve.*
|
||
|
||
---
|
||
|
||
## 1. Build, Lint, Test
|
||
|
||
### Available npm scripts
|
||
```json
|
||
{
|
||
"build": "tsc --project tsconfig.build.json",
|
||
"lint": "eslint . --ext .ts,.tsx,.js,.jsx",
|
||
"format": "prettier --write .",
|
||
"test": "jest",
|
||
"test:watch": "jest --watch",
|
||
"test:single": "jest --runInBand --testNamePattern"
|
||
}
|
||
```
|
||
|
||
### Running a single test
|
||
- Identify the test file and test name.
|
||
- Use `npm run test:single -- -t <testName>` to run only that test.
|
||
- Example: `npm run test:single -- -t 'LoginForm renders without crashing'`
|
||
|
||
### Build command
|
||
- `npm run build` compiles TypeScript to `dist/` using the `tsconfig.build.json` configuration.
|
||
- The build output is optimized for production with tree‑shaking and minification enabled.
|
||
|
||
### Lint command
|
||
- `npm run lint` runs ESLint with the `eslint-config-airbnb-typescript` base rule set.
|
||
- Fail the CI if any lint error has severity `error`.
|
||
|
||
### Test command
|
||
- `npm run test` executes Jest with coverage collection.
|
||
- Use `npm run test -- --coverage` to generate a coverage report in `coverage/`.
|
||
- For debugging, run `npm run test:watch` to re‑run tests on file changes.
|
||
|
||
---
|
||
|
||
## 2. Code Style Guidelines
|
||
|
||
### Imports
|
||
1. **Core modules** – place Node built‑in imports last.
|
||
2. **Third‑party libraries** – alphabetically sorted, each on its own line.
|
||
3. **Local relative paths** – end with `.js` or `.ts`; avoid index extensions.
|
||
4. **Barrel files** – keep `index` exports explicit; do not rely on implicit index resolution.
|
||
|
||
```ts
|
||
// Good
|
||
import { useEffect } from 'react';
|
||
import { formatDate } from '@utils/date';
|
||
import { User } from './types';
|
||
import { apiClient } from './api/client';
|
||
|
||
// Bad
|
||
import { foo } from './foo';
|
||
import React from 'react';
|
||
```
|
||
|
||
### Formatting
|
||
- Use Prettier with the shared `.prettierrc`.
|
||
- Enforce 2‑space indentation.
|
||
- Keep line length ≤ 100 characters; wrap when necessary.
|
||
- Always include a trailing newline.
|
||
|
||
### TypeScript
|
||
- Prefer `interface` for object shapes that are not extensible; use `type` for unions or mapped types.
|
||
- Enable `strictNullChecks` and `noImplicitAny`.
|
||
- Use `readonly` for immutable props.
|
||
- Export explicit types in a `types.ts` file next to feature modules.
|
||
|
||
### Naming Conventions
|
||
| Element | Convention |
|
||
|---------|------------|
|
||
| Files | kebab-case (`user-profile.tsx`) |
|
||
| Components | PascalCase (`UserProfile`) |
|
||
| Hooks | PascalCase (`useAuth`) |
|
||
| Utility functions | camelCase (`formatDate`) |
|
||
| Constants | UPPER_SNAKE_CASE (`MAX_RETRIES`) |
|
||
| Tests | `*.test.tsx` or `*.spec.ts` |
|
||
|
||
### Error Handling
|
||
- Throw `AppError` (or a subclass) for domain‑specific errors; never expose raw `Error` objects to UI.
|
||
- Centralize error messages in `src/errors.ts`.
|
||
- Log errors with `console.error` and include a unique error code.
|
||
|
||
### Logging
|
||
- Use `pino` with a structured JSON logger.
|
||
- Include request ID, module name, and error stack in each log entry.
|
||
- Do not log secrets or PII.
|
||
|
||
### Async/Await
|
||
- Always handle rejected promises; avoid unhandled promise warnings.
|
||
- Use `async` only when necessary; prefer `.then()` chains for simple pipelines.
|
||
|
||
### Git Workflow
|
||
- Commit message format: `<type>(<scope>): <subject>`
|
||
- Types: `feat`, `fix`, `docs`, `refactor`, `test`, `chore`
|
||
- Example: `feat(auth): add OAuth2 token refresh`
|
||
- Rebase locally before pushing; keep the history linear.
|
||
- Never force‑push to `main`; use feature‑branch PRs.
|
||
|
||
### CI/CD
|
||
- GitHub Actions run on every PR:
|
||
1. Lint
|
||
2. Type‑check (`npm run typecheck`)
|
||
3. Unit tests
|
||
4. Build
|
||
- Merge only after all checks pass.
|
||
|
||
### Dependency Management
|
||
- Keep `package.json` dependencies grouped:
|
||
- `"dependencies"` for production.
|
||
- `"devDependencies"` for tooling.
|
||
- Run `npm audit` weekly; update with `npm audit fix`.
|
||
|
||
### Security
|
||
- Never commit secrets; use `dotenv` only in local dev.
|
||
- Validate all inputs before using them in SQL queries or HTTP requests.
|
||
- Apply Content Security Policy via the `csp` middleware.
|
||
|
||
### Testing
|
||
- Unit tests should be pure and fast; mock side effects.
|
||
- Integration tests verify the contract between modules.
|
||
- End‑to‑end tests live under `e2e/` and use Playwright.
|
||
|
||
---
|
||
|
||
## 3. Agentic Interaction Rules
|
||
|
||
1. **Task Management** – Use the `todo` tool to track multi‑step work. Only one task may be `in_progress` at a time.
|
||
2. **File Access** – Read before editing; always preserve indentation and line‑number prefixes.
|
||
3. **Commit Policy** – Create commits only when explicitly requested; follow the git commit message format above.
|
||
4. **Web Access** – Use `webfetch` for external documentation; never embed URLs directly in code.
|
||
5. **Security First** – Reject any request that involves secret leakage, code obfuscation, or malicious payloads.
|
||
|
||
6. **Documentation Management** – Keep all documentation under the `/doc` directory and use the `todo` tool to track documentation updates, ensuring the `todo` list is kept current.
|
||
|
||
7. **Memory Updates** – When a user instructs the agent to remember information, the agent must record the instruction in `@AGENTS.md` (or relevant documentation) to preserve it for future reference.
|
||
|
||
---
|
||
|
||
## 4. Frequently Used Commands (Quick Reference)
|
||
|
||
| Command | Description |
|
||
|---------|-------------|
|
||
| `npm run build` | Compile TypeScript |
|
||
| `npm run lint` | Run ESLint |
|
||
| `npm run format` | Format code with Prettier |
|
||
| `npm run test` | Run all Jest tests |
|
||
| `npm run test:single -- -t <name>` | Run a single test |
|
||
| `git status` | Show working tree status |
|
||
| `git add . && git commit -m "feat: ..."` | Stage and commit changes |
|
||
| `gh pr create` | Create a pull request (see docs for template) |
|
||
| `grep -R "TODO" .` | Find TODO comments |
|
||
| `grep -R "console.log" src/` | Locate stray logs |
|
||
|
||
---
|
||
|
||
*End of document* |