After the PRD is finalized in the docs/ directory, the next step is to decide on the technology foundation and storage solution. This is often where solo developers are most prone to making mistakes in their choices (“I heard Supabase is hot right now, so I'll use that. Oh, wait, I heard Prisma is great too...”).
Here, we will fully leverage the "external brain" mechanism that planning-with-files provides to the Agent (specifically, the findings.md document).
1. Introspective Inquiry: An Unbiased Tech Stack Debate
Issue the following command in the Agent interface:
"Based on the overall
PRD_System_Design.md, we now need to build a robust cross-device synchronization transaction layer. Please conduct a comparative analysis of a pure Prisma + Postgres setup, the Supabase ecosystem, and a pure Drizzle ORM setup to determine which is most suitable for us. Provide your reasoning process. After reaching a conclusion, append our chosen solution and the rationale for the decision todocs/findings.md(as a distinct decision assertion)."
2. What Constitutes a Good "Diagnostic Write"?
A smart architect Agent (instructed by GEMINI.md to pursue minimalism and a low barrier to entry) will analyze and conclude things like:
- Supabase's built-in Auth and real-time features are very appealing, but for our specific use case—a single-user application focused solely on Google Calendar sync with no multi-tenancy—it's slightly overkill.
- Prisma offers a better DX (Developer Experience) and is perfectly suited for use with Next.js Server Actions.
After the Agent confirms the decision to use Prisma, it will silently call the write_to_file tool or execute a command like cat >> in the background (the system will have specific tool instruction mechanisms to follow) to inject a permanent record into your docs/findings.md:
<!-- Snippet from docs/findings.md -->
### [Decision Record] Database and Storage Selection (2026-X-X)
- **Choice**: PostgreSQL + Prisma ORM
- **Rationale**: The system heavily relies on transactional operations for Google Calendar synchronization. Prisma's interactive transaction support makes rolling back local data streams very safe, with the added benefit of type inference.
- **Rejected Alternatives**: Forgoing a custom Auth system. We will rely purely on Google OAuth sessions for passwordless management.
3. The Power of ADR (Architecture Decision Records)
In software engineering, this is called an Architecture Decision Record (ADR).
In traditional development, only highly disciplined teams maintain ADRs. But here, not only do you no longer have to write them manually, they are also written for future "Agent sub-processes" to read!
Tomorrow, when your testing Agent runs into an E2E error and questions why the Supabase user table system wasn't used, the main controller Agent can simply read findings.md and firmly state, "Because we decided against it during the initial architecture design." This prevents the entire development process from falling into a self-defeating cycle of second-guessing.