ca6a34c6d4
- Add Philosophy blockquote: recommendations only, not changelog - Replace "Open Questions" with "Recommended Improvements" (delete completed, don't strikethrough) - Replace "Change Log" with "Deployment Notes" - Add RECOMMENDATIONS.md Cleanup Rules to status-update-checklist - Add docs/phases-plan.md to phase transition checklist - Add strikethrough grep check to verification commands Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
3.8 KiB
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/.
Philosophy: This file contains recommendations (what to do next) and locked decisions (what was agreed upon). It is NOT a changelog or accomplishments log. Keep completed work in git history,
docs/phases/, anddocs/improvements/.
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. Recommended Improvements
[Add audit findings, improvement suggestions, and next steps here. Group by category if needed.]
6. Deployment Notes
[Pre-deploy checklist items, migration scripts, environment changes needed]
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