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>
97 lines
3.8 KiB
Markdown
97 lines
3.8 KiB
Markdown
# 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/`, and `docs/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
|
||
|
||
<!--
|
||
This section is for ACTIONABLE recommendations — things to do next.
|
||
When an item is completed, REMOVE it from here (don't strikethrough).
|
||
Record completed work in git commits and docs/phases/ instead.
|
||
-->
|
||
|
||
_[Add audit findings, improvement suggestions, and next steps here. Group by category if needed.]_
|
||
|
||
## 6. Deployment Notes
|
||
|
||
<!-- Active deployment concerns only. Remove items once deployed and verified. -->
|
||
|
||
_[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_
|