Project-Specific Recommendations & Overrides

This file is the project-specific layer on top of the generic template.
Humans and AI agents should treat it as the single place to record locked decisions, non‑negotiable constraints, and intentional deviations from docs/ guidance.

Update this file whenever you make a decision that changes the stack, scope, constraints, or any recommendation in docs/.

1. Project Context (fill in)

Domain / product type: [e.g., customer support AI, compliance assistant, content classifier]
Chosen archetype: [A–E from /docs/archetypes.md]
Modules in scope: [core AI, integrations, pipeline, human feedback, reporting, billing, tenancy, events, queues]
Primary users: [roles/personas]
Key success metrics: [latency, accuracy, cost, adoption, etc.]
Current phase: Phase 0 / 1 / 2 / 3 / 4
Repos/services in scope: [monorepo, separate FE/BE, workers, etc.]

2. Locked Stack Decisions (override template here)

If a choice is not listed here, the default recommendations in docs/ apply.

Frontend

Framework: Next.js (App Router) / other
Language: TypeScript / other
Styling: Tailwind CSS / other
Server/Client data layer: React Query / SWR / other
Forms & validation: React Hook Form + Zod / other
Auth client: Clerk / Auth.js / other

Backend

Runtime/language: Node.js (LTS) + TypeScript / other
Framework: Express / Fastify / other
Database: Postgres / other (vector search: pgvector / other)
Queues/workers: BullMQ (Redis) / other
LLM provider & helper: Single abstraction (e.g., callLLM()), provider [fill in]
File/storage: S3/Supabase Storage/local / other

Infra / DevOps

Hosting/deploy: [Vercel/Fly/K8s/etc.]
CI/CD: [GitHub Actions/GitLab/etc.]
Observability: [Sentry/OTel/Prometheus/etc.]
Environments: dev/stage/prod (or specify)

3. Non‑Negotiable Constraints (add to RULES scope)

Compliance/regulation: [PII/PHI/PCI, SOC2, GDPR, etc.]
Data residency/retention: [regions, retention window]
Performance/SLOs: [e.g., p95 < X ms, batch window]
Cost limits: [monthly LLM budget, infra cap]
Target platforms: [browsers/devices, locales]
Repository constraints: [additional forbidden commands, branching rules, etc.]

4. Deviations From Template (explicit trade-offs)

List any intentional departures from docs/ recommendations and why.

[Decision] → [Why] → [Migration/rollback plan if relevant]

5. Open Questions / To Confirm

[Unresolved item] → [owner] → [ETA]

6. Change Log (optional)

YYYY‑MM‑DD: [decision summary]

7. Architecture Decision Records (ADRs)

Record major decisions and their rationale in docs/adr/.

Example ADRs you may need:

ADR: modular monolith vs microservices
ADR: vector storage choice (pgvector vs external)
ADR: billing model/provider
ADR: RAG strategy and retrieval stack
ADR: auth/tenancy model

Once accepted, link ADRs here:

docs/adr/0001-<title>.md — accepted

3.2 KiB Raw Blame History Unescape Escape