AI-Assisted Build Workflow

We rely on Claude Code (planning) and Codex (review/iteration). You are the supervisor - you write prompts, drive structure, check outputs, run code, read logs, and iterate.

Core Planning Ritual

Inside Claude Code, establish your project foundation with these driver documents:

Create claude.md

Project summary, constraints, target users, KPIs, and explicit tech stack

Create plan.md

Phased implementation plan with tiny milestones and explicit tasks

Create agents.md

Define tools, repos, APIs, and roles for each agent

Use Magic Keys

Apply depth when needed: ultrathink, think deeply, think

Driver Documents

claude.md Template

# Project: [Name]

## Summary
[2-3 sentences describing the project]

## Tech Stack (BE EXPLICIT)
- Frontend: Next.js 14 + shadcn/ui + Tailwind
- Backend: Supabase + Edge Functions
- AI: LangChain + LangGraph
- Deployment: Vercel

## Constraints
- Use battle-tested OSS libraries wherever possible
- Avoid custom logic unless necessary
- Plan phases so each can be implemented & tested independently

## Target Users
[Who will use this and why]

## Success Metrics
- [KPI 1]
- [KPI 2]

plan.md Structure

# Implementation Plan

## Phase 0: Foundation (Day 1)
- [ ] Scaffold project with Next.js
- [ ] Configure environments (.env.local)
- [ ] Set up CI/CD pipeline
- [ ] Initialize Sentry

## Phase 1: Core Features (Days 2-3)
- [ ] Auth flow with Supabase
- [ ] Database schema and migrations
- [ ] Seed data
- [ ] Basic UI shell

## Phase 2: Business Logic (Days 4-5)
- [ ] [Feature specific tasks]

## Phase 3: Polish (Day 6)
- [ ] E2E tests
- [ ] Performance optimization
- [ ] Documentation

agents.md Roles

# Agent Responsibilities

## Claude Code (CC)
- Planning & code generation
- Architecture decisions
- Complex implementations

## Codex
- Code review
- Refactoring suggestions
- Test generation
- Security audits

## Runner
- Execute commands
- Capture logs
- Test execution

## Docs Agent
- Fetch library examples
- API documentation
- Best practices

Prompt Power-Ups

Architecture
Data Modeling
Testing
Refactoring

ultrathink this architecture for edge cases,
rate limits, and fallbacks

think deeply about data modeling with
Postgres for multi-tenant isolation

Draft unit tests and Playwright specs
for the new authentication flow

Refactor to remove custom helpers
in favor of library lodash methods

From Plan to Code

Repository Setup

# Create or clone repo
git clone [repo-url]
cd [repo-name]
pnpm i

Branch Strategy

# Feature branches
git checkout -b feat/user-auth

# Fix branches
git checkout -b fix/login-error

Development Loop

# Start dev server
pnpm dev

# Run tests continuously
pnpm test --watch

Tight Iteration

Feed exact errors/logs to CC/Codex:

Getting this TypeScript error:
[paste exact error]

Here's the current code:
[paste relevant code]

Effective Prompting

Good Prompts

Specific Implementation

Using Next.js 14 app router and Supabase,
create a protected dashboard route that:
1. Checks authentication in middleware
2. Fetches user profile with RLS
3. Displays data in shadcn DataTable
Include error boundaries and loading states.

Debug with Context

This Supabase query returns null:
[paste query]

RLS policies:
[paste policies]

Auth context:
[paste session info]

What's wrong and how do I fix it?

Test Generation

Generate Playwright e2e tests for:
- Login flow with valid credentials
- Login with invalid credentials
- Password reset flow
- Session timeout handling

Use our existing test helpers from tests/utils.ts

Prompt Templates

I need to architect a [feature] that:
- Requirement 1
- Requirement 2

Current stack:
- [List your stack]

Constraints:
- [Any limitations]

Provide:
1. Component structure
2. Data flow
3. Error handling strategy

Error: [paste error]

Context:
- File: [filename]
- Line: [line number]
- Trigger: [what causes it]

Relevant code:
[paste code]

Previous attempts:
- [what you tried]

What's the root cause and solution?

Review this implementation for:
- Security vulnerabilities
- Performance issues
- Best practice violations
- Missing edge cases

Code:
[paste diff or code]

Suggest specific improvements.

Working with Codex

After Claude Code generates, use Codex for review:

Share Diff

git diff > changes.diff
# Paste diff to Codex

Request Review

Review this diff for:
- Security issues
- Performance problems
- Missing error handling
- Test coverage gaps

Iterate

Apply suggestions and re-run review until clean

Common Workflows

New Feature
Bug Fix
Refactor

Update plan.md with feature requirements
Ask CC to generate implementation plan
Generate code incrementally
Test each piece locally
Codex review → refactor
Write tests
Commit with conventional message

Best Practices

Always specify your tech stack explicitly - don’t let AI guess what libraries you’re using

Use battle-tested libraries - explicitly tell AI to prefer proven OSS over custom implementations

Small, atomic prompts work better than large, complex ones. Break down big tasks.

Troubleshooting

AI generates wrong library usage

Always specify exact versions and import styles:

Using Next.js 14 with app router (not pages),
Supabase JS client v2 (not v1),
shadcn/ui components from @/components/ui

Generated code doesn't match style

Provide examples from your codebase:

Follow this pattern from our codebase:
[paste existing code example]

Complex logic gets confused

Break into smaller steps:

Step 1: Just create the database schema
Step 2: Now add the RLS policies
Step 3: Create the API route

AI Workflows

Prompting Guide

Model Training

Core Planning Ritual

Driver Documents

claude.md Template

plan.md Structure

agents.md Roles

Prompt Power-Ups

From Plan to Code

Effective Prompting

Good Prompts

Prompt Templates

Working with Codex

Common Workflows

Best Practices

Troubleshooting

​Core Planning Ritual

​Driver Documents

​claude.md Template

​plan.md Structure

​agents.md Roles

​Prompt Power-Ups

​From Plan to Code

​Effective Prompting

​Good Prompts

​Prompt Templates

​Working with Codex

​Common Workflows

​Best Practices

​Troubleshooting

Core Planning Ritual

Driver Documents

claude.md Template

plan.md Structure

agents.md Roles

Prompt Power-Ups

From Plan to Code

Effective Prompting

Good Prompts

Prompt Templates

Working with Codex

Common Workflows

Best Practices

Troubleshooting