92 lines
3.0 KiB
Plaintext
92 lines
3.0 KiB
Plaintext
# ${PROJECT_NAME} — Agent Context
|
|
|
|
> Guidelines for AI agents working on this NestJS + Next.js monorepo.
|
|
> **Update this file** when you discover reusable patterns or non-obvious requirements.
|
|
|
|
## Codebase Patterns
|
|
|
|
- **Monorepo structure:** pnpm workspaces + TurboRepo
|
|
- `apps/api/` — NestJS backend
|
|
- `apps/web/` — Next.js frontend
|
|
- `packages/shared/` — Shared types and utilities
|
|
- **Database:** Prisma ORM — schema at `apps/api/prisma/schema.prisma`
|
|
- **Auth:** Configured in `apps/api/src/auth/`
|
|
- **API:** RESTful with DTOs for validation
|
|
|
|
## Common Gotchas
|
|
|
|
- **Always run `pnpm install`** after pulling — lockfile changes frequently
|
|
- **Prisma generate** after schema changes: `pnpm --filter api prisma generate`
|
|
- **Environment variables:** Frontend vars need `NEXT_PUBLIC_` prefix
|
|
- **Import paths:** Use `@shared/` alias for shared package imports
|
|
- **Tests require running database:** Set `DATABASE_URL` in `.env.test`
|
|
- **TurboRepo caching:** Run `pnpm clean` if builds behave unexpectedly
|
|
|
|
## Context Management
|
|
|
|
Context = tokens = cost. Be smart.
|
|
|
|
| Strategy | When |
|
|
|----------|------|
|
|
| **Spawn sub-agents** | Isolated coding tasks, research |
|
|
| **Batch operations** | Group related API calls |
|
|
| **Check existing patterns** | Before writing new code |
|
|
| **Minimize re-reading** | Don't re-read files you just wrote |
|
|
|
|
## Quality Gates
|
|
|
|
**All must pass before any commit:**
|
|
|
|
```bash
|
|
pnpm typecheck && pnpm lint && pnpm test
|
|
```
|
|
|
|
## Orchestrator Integration
|
|
|
|
### Task Prefix
|
|
Use `${TASK_PREFIX}` for orchestrated tasks (e.g., `${TASK_PREFIX}-SEC-001`).
|
|
|
|
### Worker Checklist
|
|
1. Read the finding details from the report
|
|
2. Implement the fix following existing patterns
|
|
3. Run quality gates (ALL must pass)
|
|
4. Commit: `git commit -m "fix({finding_id}): brief description"`
|
|
5. Push: `git push origin {branch}`
|
|
6. Report result as JSON
|
|
|
|
### Post-Coding Review
|
|
After implementing changes, the orchestrator will run:
|
|
1. **Codex code review** — `~/.config/mosaic/rails/codex/codex-code-review.sh --uncommitted`
|
|
2. **Codex security review** — `~/.config/mosaic/rails/codex/codex-security-review.sh --uncommitted`
|
|
3. If blockers/critical findings: remediation task created
|
|
4. If clean: task marked done
|
|
|
|
## Workflow (Non-Negotiable)
|
|
|
|
```
|
|
1. Branch → git checkout -b feature/XX-description
|
|
2. Code → TDD: write test (RED), implement (GREEN), refactor
|
|
3. Test → pnpm test (must pass)
|
|
4. Push → git push origin feature/XX-description
|
|
5. PR → Create PR to develop (not main)
|
|
6. Review → Wait for approval or self-merge if authorized
|
|
7. Close → Close related issues
|
|
```
|
|
|
|
**Never merge directly to develop without a PR.**
|
|
|
|
## Key Files
|
|
|
|
| File | Purpose |
|
|
|------|---------|
|
|
| `CLAUDE.md` | Project overview and conventions |
|
|
| `apps/api/prisma/schema.prisma` | Database schema |
|
|
| `apps/api/src/` | Backend source |
|
|
| `apps/web/app/` | Frontend pages |
|
|
| `packages/shared/` | Shared types |
|
|
| `.env.example` | Required environment variables |
|
|
|
|
---
|
|
|
|
_Model-agnostic. Works for Claude, Codex, GPT, Llama, etc._
|