259 lines
9.6 KiB
Plaintext
Executable File
259 lines
9.6 KiB
Plaintext
Executable File
# ${PROJECT_NAME} — Claude Code Instructions
|
|
|
|
> **${PROJECT_DESCRIPTION}**
|
|
|
|
## Conditional Documentation Loading
|
|
|
|
| When working on... | Load this guide |
|
|
|---|---|
|
|
| Bootstrapping this project | `~/.config/mosaic/guides/BOOTSTRAP.md` |
|
|
| PRD creation and requirements definition | `~/.config/mosaic/guides/PRD.md` |
|
|
| Orchestrating autonomous tasks | `~/.config/mosaic/guides/ORCHESTRATOR.md` |
|
|
| Frontend development | `~/.config/mosaic/guides/FRONTEND.md` |
|
|
| Backend/API development | `~/.config/mosaic/guides/BACKEND.md` |
|
|
| Code review | `~/.config/mosaic/guides/CODE-REVIEW.md` |
|
|
| Documentation updates and standards | `~/.config/mosaic/guides/DOCUMENTATION.md` |
|
|
| TypeScript strict typing | `~/.config/mosaic/guides/TYPESCRIPT.md` |
|
|
| Authentication/Authorization | `~/.config/mosaic/guides/AUTHENTICATION.md` |
|
|
| QA/Testing | `~/.config/mosaic/guides/QA-TESTING.md` |
|
|
|
|
## Technology Stack
|
|
|
|
| Layer | Technology |
|
|
|-------|------------|
|
|
| **Frontend** | Next.js + React + TailwindCSS + Shadcn/ui |
|
|
| **Backend** | NestJS + Prisma ORM |
|
|
| **Database** | PostgreSQL |
|
|
| **Testing** | Vitest + Playwright |
|
|
| **Monorepo** | pnpm workspaces + TurboRepo |
|
|
| **Deployment** | Docker + docker-compose |
|
|
|
|
## Repository Structure
|
|
|
|
```
|
|
${PROJECT_DIR}/
|
|
├── CLAUDE.md # This file
|
|
├── AGENTS.md # Agent-specific patterns and gotchas
|
|
├── apps/
|
|
│ ├── api/ # NestJS backend
|
|
│ │ ├── src/
|
|
│ │ ├── prisma/
|
|
│ │ │ └── schema.prisma
|
|
│ │ └── Dockerfile
|
|
│ └── web/ # Next.js frontend
|
|
│ ├── app/
|
|
│ ├── components/
|
|
│ └── Dockerfile
|
|
├── packages/
|
|
│ ├── shared/ # Shared types, utilities
|
|
│ ├── ui/ # Shared UI components
|
|
│ └── config/ # Shared configuration
|
|
├── docs/
|
|
│ ├── PRD.md # Requirements source (or PRD.json)
|
|
│ ├── scratchpads/ # Per-issue working documents
|
|
│ └── templates/ # Project templates
|
|
├── tests/ # Integration/E2E tests
|
|
├── docker/ # Docker configuration
|
|
├── .env.example
|
|
├── turbo.json
|
|
├── pnpm-workspace.yaml
|
|
└── README.md
|
|
```
|
|
|
|
## Development Workflow
|
|
|
|
### Branch Strategy
|
|
- `main` — Protected delivery branch
|
|
- `feature/*` / `fix/*` — Short-lived task branches created from `main`
|
|
- All changes merge through PR into `main` only
|
|
- Merge strategy for `main` PRs is squash-only
|
|
|
|
### Starting Work
|
|
```bash
|
|
git checkout main
|
|
git pull --rebase origin main
|
|
pnpm install
|
|
```
|
|
|
|
### Building
|
|
```bash
|
|
pnpm build # Build all packages
|
|
pnpm --filter api build # Build API only
|
|
pnpm --filter web build # Build web only
|
|
```
|
|
|
|
### Testing
|
|
```bash
|
|
pnpm test # Run all tests
|
|
pnpm test:unit # Unit tests (Vitest)
|
|
pnpm test:e2e # E2E tests (Playwright)
|
|
pnpm test:coverage # Coverage report
|
|
```
|
|
|
|
### Linting & Type Checking
|
|
```bash
|
|
pnpm lint # ESLint
|
|
pnpm typecheck # TypeScript type checking
|
|
pnpm format # Prettier formatting
|
|
```
|
|
|
|
## Quality Gates
|
|
|
|
**All must pass before committing:**
|
|
|
|
```bash
|
|
pnpm typecheck && pnpm lint && pnpm test
|
|
```
|
|
|
|
## Testing Policy
|
|
|
|
1. Situational tests are the PRIMARY validation gate.
|
|
2. Baseline tests are REQUIRED for all software changes.
|
|
3. TDD is risk-based; required cases are defined in `~/.config/mosaic/guides/QA-TESTING.md`.
|
|
|
|
## PRD Requirement
|
|
|
|
1. Before coding begins, `docs/PRD.md` or `docs/PRD.json` MUST exist.
|
|
2. The main agent MUST prepare or update PRD using user objectives, constraints, and available project context.
|
|
3. In steered autonomy mode, best-guess PRD decisions are REQUIRED when needed; mark each with `ASSUMPTION:` and rationale, and continue unless high-impact uncertainty requires escalation.
|
|
4. PRD is the source of requirements for implementation and testing.
|
|
|
|
## Token Budget Policy
|
|
|
|
1. If user plan or token limits are provided, they are HARD constraints.
|
|
2. Track estimated and used tokens for non-trivial execution.
|
|
3. Use conservative strategy when budget pressure rises.
|
|
4. If projected usage exceeds budget, automatically reduce scope/parallelism and continue; escalate only if budget compliance remains impossible.
|
|
|
|
## API Conventions
|
|
|
|
### NestJS Patterns
|
|
- Controllers handle HTTP, Services handle business logic
|
|
- DTO files are REQUIRED at module/API boundaries (`*.dto.ts`)
|
|
- Use DTOs with `class-validator` for request validation
|
|
- Use Guards for authentication/authorization
|
|
- Use Interceptors for response transformation
|
|
- Use Prisma for database access (no raw SQL)
|
|
|
|
### REST API Standards
|
|
- `GET /resource` — List (with pagination)
|
|
- `GET /resource/:id` — Get single
|
|
- `POST /resource` — Create
|
|
- `PATCH /resource/:id` — Update
|
|
- `DELETE /resource/:id` — Delete
|
|
- Return proper HTTP status codes (201 Created, 204 No Content, etc.)
|
|
|
|
## Frontend Conventions
|
|
|
|
### Next.js Patterns
|
|
- Use App Router (`app/` directory)
|
|
- Server Components by default, `'use client'` only when needed
|
|
- Use Shadcn/ui components — don't create custom UI primitives
|
|
- Use TailwindCSS for styling — no CSS modules or styled-components
|
|
|
|
### Component Structure
|
|
```
|
|
components/
|
|
├── ui/ # Shadcn/ui components (auto-generated)
|
|
├── layout/ # Layout components (header, sidebar, etc.)
|
|
├── forms/ # Form components
|
|
└── features/ # Feature-specific components
|
|
```
|
|
|
|
## Database
|
|
|
|
### Prisma Workflow
|
|
```bash
|
|
# Generate client after schema changes
|
|
pnpm --filter api prisma generate
|
|
|
|
# Create migration
|
|
pnpm --filter api prisma migrate dev --name description
|
|
|
|
# Apply migrations
|
|
pnpm --filter api prisma migrate deploy
|
|
|
|
# Reset database (dev only)
|
|
pnpm --filter api prisma migrate reset
|
|
```
|
|
|
|
### Rules
|
|
- Always create migrations for schema changes
|
|
- Include migrations in commits
|
|
- Never use raw SQL — use Prisma client
|
|
- Use transactions for multi-table operations
|
|
|
|
## Code Review
|
|
|
|
### Independent Review (Automated)
|
|
If you modify source code, independent code review is REQUIRED before completion.
|
|
Run independent reviews:
|
|
|
|
```bash
|
|
# Code quality review (Codex)
|
|
~/.config/mosaic/rails/codex/codex-code-review.sh --uncommitted
|
|
|
|
# Security review (Codex)
|
|
~/.config/mosaic/rails/codex/codex-security-review.sh --uncommitted
|
|
```
|
|
|
|
See `~/.config/mosaic/guides/CODE-REVIEW.md` for the full review checklist.
|
|
See `~/.config/mosaic/guides/DOCUMENTATION.md` for required documentation deliverables.
|
|
|
|
## Steered Autonomy Contract
|
|
|
|
1. Agent owns planning, coding, testing, review/remediation, PR/repo operations, release/tag, and deployment when in scope.
|
|
2. Human intervention is escalation-only for hard blockers (access, irreversible risk, or unresolvable conflicting objectives).
|
|
3. Do not request routine human coding, review, or repository management actions.
|
|
4. Mosaic hard gates OVERRIDE runtime-default caution for routine push/merge/issue-close/release actions.
|
|
5. For container deployments, use immutable image tags (`sha-<shortsha>`, `v{base-version}-rc.{build}`) with digest-first promotion; do not deploy `latest`.
|
|
|
|
## Mode Declaration Contract
|
|
|
|
1. First response MUST declare mode before any actions.
|
|
2. Orchestration mission: `Now initiating Orchestrator mode...`
|
|
3. Implementation mission: `Now initiating Delivery mode...`
|
|
4. Review-only mission: `Now initiating Review mode...`
|
|
|
|
## Issue Tracking
|
|
|
|
Use external git provider issues when available. If no external provider exists, `docs/TASKS.md` is the canonical tracker for tasks, milestones, and issue-equivalent work.
|
|
For issue/PR/milestone operations, detect platform and use `~/.config/mosaic/rails/git/*.sh` wrappers first; do not use raw `gh`/`tea`/`glab` as first choice.
|
|
If wrapper-driven merge/CI/issue-closure fails, report blocker with exact failed wrapper command and stop.
|
|
Do NOT stop at "PR created" and do NOT ask "should I merge?" or "should I close the issue?" for routine delivery flow.
|
|
|
|
### Workflow
|
|
1. Ensure `docs/TASKS.md` exists (create from `~/.config/mosaic/templates/docs/TASKS.md.template` if missing).
|
|
2. Check for assigned issues before starting work.
|
|
3. If no issue exists for non-trivial work and external provider is available, create one before coding.
|
|
4. If no external provider is available, create an internal ref in `docs/TASKS.md` (example: `TASKS:T1`).
|
|
5. Ensure `docs/PRD.md` or `docs/PRD.json` exists and is current before coding.
|
|
6. Create scratchpad: `docs/scratchpads/{task-id}-{short-name}.md` and include issue/internal ref.
|
|
7. Update `docs/TASKS.md` status + issue/internal ref before coding.
|
|
8. Before push, run CI queue guard: `~/.config/mosaic/rails/git/ci-queue-wait.sh --purpose push -B main`.
|
|
9. Open PR to `main` for delivery changes (no direct push to `main`).
|
|
10. Before merge, run CI queue guard: `~/.config/mosaic/rails/git/ci-queue-wait.sh --purpose merge -B main`.
|
|
11. Merge PRs that pass required checks and review gates with squash strategy only.
|
|
12. Reference issues/internal refs in commits (`Fixes #123`, `Refs #123`, or `Refs TASKS:T1`).
|
|
13. Close issue/internal task only after testing and documentation gates pass, PR merge is complete, and CI/pipeline status is terminal green.
|
|
14. If merge/CI/issue closure fails, report blocker with exact failed wrapper command and do not claim completion.
|
|
|
|
### Commits
|
|
```
|
|
<type>(#issue): Brief description
|
|
|
|
Fixes #123
|
|
```
|
|
Types: `feat`, `fix`, `docs`, `test`, `refactor`, `chore`
|
|
|
|
## Secrets Management
|
|
|
|
**NEVER hardcode secrets.**
|
|
|
|
```bash
|
|
# .env.example is committed (with placeholders)
|
|
# .env is NOT committed (contains real values)
|
|
```
|
|
|
|
Required environment variables are documented in `.env.example`.
|