How We Start Projects

Every project starts with a request from somewhere in the company. This guide covers how we turn that request into a working project.

Core question: What problem are we solving and how will we know we've solved it?

The Starting Process

Request → Clarify → PRD → Repo Setup → Claude Planning → First Sprint

Step 1: Clarify the Request

Requests come in various forms: Slack messages, meetings, emails. Before writing anything:

Questions to Ask

Example: AI Overviews Checker

Raw request: "We need a tool to check AI Overviews for our clients' keywords"

After clarification:

• Users: SEO team (5-10 people)
• Deadline: 2 weeks for MVP
• Success: Can check 100+ keywords at once, see which have AI Overviews
• APIs: DataForSEO SERP API
• Existing: Manual checking in Google (slow)

Step 2: Write the PRD

A Product Requirements Document captures what we're building. Keep it simple.

PRD Template

# [Project Name] PRD

## Problem
What pain point are we solving? Who has this pain?

## Solution
High-level description of what we're building.

## Users
Who will use this? How often? What's their technical level?

## Requirements

### Must Have (MVP)
- [ ] Requirement 1
- [ ] Requirement 2

### Should Have (v1.1)
- [ ] Nice-to-have 1

### Won't Have (explicitly out of scope)
- Not building X
- Not supporting Y

## Technical Constraints
- Must use existing Supabase instance
- Must integrate with DataForSEO
- Budget: $X/month for API costs

## Success Metrics
- Can process 100 keywords in under 5 minutes
- 90% accuracy compared to manual checking

## Timeline
- Week 1: MVP
- Week 2: Polish and deploy

## Open Questions
- [ ] How do we handle rate limits?
- [ ] Do we need user accounts?

PRD Best Practices

Step 3: Set Up the Repository

Create GitHub Repo

1. Go to GitHub → New Repository
2. Name it descriptively: keyword-clustering-tool not project1
3. Add README, .gitignore (Node or Python), and MIT license
4. Clone to your machine

Initial Project Structure

For a NextJS project:

# Create NextJS app
npx create-next-app@latest project-name --typescript --tailwind --eslint --app

# Navigate in
cd project-name

# Add Shadcn UI
npx shadcn-ui@latest init

# Add common dependencies
npm install @supabase/supabase-js

Essential Files to Create

project/
├── .env.example          # Template for environment variables
├── .env.local           # Local env vars (git-ignored)
├── README.md            # Project overview
├── CHANGELOG.md         # Track changes
├── docs/
│   └── PRD.md          # The PRD
└── src/
    └── ...             # Code

.env.example Template

# Database
SUPABASE_URL=
SUPABASE_ANON_KEY=
SUPABASE_SERVICE_ROLE_KEY=

# External APIs
DATAFORSEO_LOGIN=
DATAFORSEO_PASSWORD=

# AI
ANTHROPIC_API_KEY=
OPENAI_API_KEY=

# App
NEXT_PUBLIC_APP_URL=http://localhost:3000

Step 4: Plan with Claude Code

This is where AI-assisted development shines. Before writing code, have a planning conversation.

Planning Prompt Template

I'm starting a new project: [project name]

## Context
[Paste your PRD or key requirements]

## Tech Stack
- NextJS 14 with App Router
- Supabase for database
- Tailwind CSS + Shadcn UI
- [Any other specific tech]

## Questions
1. What should the folder structure look like?
2. What database tables do we need?
3. What are the main components?
4. What API routes do we need?
5. What's the recommended order to build things?

Please give me a detailed technical plan before we start coding.

What Claude Should Produce

1. Folder structure — where code will live
2. Database schema — tables and relationships
3. Component breakdown — UI pieces needed
4. API endpoints — backend routes
5. Build order — what to build first

Example: Keyword Clustering Planning

Claude's response might include:

## Folder Structure
src/
├── app/
│   ├── page.tsx           # Upload keywords page
│   ├── results/
│   │   └── [id]/page.tsx  # View clustering results
│   └── api/
│       ├── upload/route.ts
│       └── cluster/route.ts
├── components/
│   ├── keyword-upload.tsx
│   ├── cluster-view.tsx
│   └── progress-indicator.tsx
└── lib/
    ├── supabase.ts
    └── clustering.ts

## Database Schema
- clustering_jobs: id, user_id, status, created_at
- keywords: id, job_id, text, cluster_id
- clusters: id, job_id, label, keywords_count

## Build Order
1. Database setup + basic UI
2. File upload + keyword parsing
3. FastAPI clustering endpoint
4. Results display
5. Polish + error handling

Validate the Plan

Before coding, check:

• Does this match the PRD requirements?
• Is the scope realistic for the timeline?
• Are there any technical unknowns?
• Does the team agree on the approach?

Step 5: First Commit

Create Initial Structure

Have Claude Code help set up the initial structure:

Based on the plan we discussed, please:
1. Create the folder structure
2. Set up the database schema (Supabase migration)
3. Create placeholder components
4. Set up environment variables

Don't implement functionality yet - just the skeleton.

Commit the Skeleton

git add .
git commit -m "Initial project structure

- Set up NextJS with Tailwind and Shadcn
- Create folder structure per technical plan
- Add database schema
- Configure environment variables

See docs/PRD.md for project requirements"

git push -u origin main

Common Mistakes

Starting to code without a PRD

Signs: Unclear requirements emerge mid-project, scope keeps changing.

Fix: Always write a PRD, even a simple one. 30 minutes of planning saves hours of rework.

Overcomplicating initial setup

Signs: Spending days on "perfect" architecture before any features work.

Fix: Start with the simplest structure that could work. Refactor later when you understand the problem better.

Not involving Claude Code in planning

Signs: You architected everything yourself, then struggle to communicate it to AI.

Fix: Let Claude help plan. It will understand its own plans better and generate more consistent code.

Skipping the skeleton commit

Signs: First commit is a massive dump of code.

Fix: Commit the structure first. Makes it easier to review and understand what's where.

Evaluation Checklist

Your project start is working if:

• There's a written PRD with clear requirements
• The repo exists with sensible structure
• .env.example documents all needed variables
• README explains what the project is
• You have a technical plan from Claude
• First commit is clean and reviewable

Your project start needs work if:

• You're coding without written requirements
• Nobody knows what "done" looks like
• Folder structure is made up as you go
• No documentation exists
• Environment setup is tribal knowledge

Quick Reference

Files Every Project Needs

Planning Conversation Starters