420 lines
11 KiB
Markdown
420 lines
11 KiB
Markdown
# App Development Playbook
|
||
> From idea to shipped app using AI assistance
|
||
> Tools: Claude Code CLI · Codex CLI · Continue + local LLMs
|
||
|
||
---
|
||
|
||
## Overview
|
||
|
||
This playbook covers the full journey from a raw idea to a working, deployed app. It is structured in five phases. Each phase has a clear goal, a set of steps, and the exact prompts to use.
|
||
|
||
The core discipline throughout: **one task per session, always**. The AI has no memory between sessions — that is a feature, not a bug. You control exactly what it knows.
|
||
|
||
---
|
||
|
||
## Your Tools and Their Roles
|
||
|
||
| Tool | Role | When to use |
|
||
|---|---|---|
|
||
| Claude (chat) | Concept partner | Phase 1 — idea to specification |
|
||
| Claude Code CLI | Architect + scaffold | Multi-file work, wiring up, audits |
|
||
| Codex CLI | Implementation | Single-feature build sessions |
|
||
| Continue + Mistral | Reviewer | After any finished component |
|
||
| Continue + Qwen | Inline fixes | Targeted edits, `Ctrl+I` |
|
||
|
||
**Rule:** Claude Code and Codex are interchangeable for implementation. Run them on the same task to compare. Mistral is always your reviewer — never skip the review step for core logic.
|
||
|
||
---
|
||
|
||
## Phase 1 — Concept
|
||
|
||
**Goal:** Lock every decision before a single file is created.
|
||
|
||
Work through this in Claude chat. Do not open VS Code.
|
||
|
||
---
|
||
|
||
### Step 1.1 — Define the idea
|
||
|
||
```
|
||
I want to build [brief description].
|
||
Let's work through the concept together before any code is written.
|
||
Ask me everything you need to know to produce a complete specification.
|
||
One question at a time.
|
||
```
|
||
|
||
Stay in this conversation until every question is answered:
|
||
- What problem does it solve?
|
||
- Who uses it, and what roles do they have?
|
||
- What is the core user flow, step by step?
|
||
- What are the edge cases and special rules?
|
||
- What is explicitly out of scope for now?
|
||
|
||
---
|
||
|
||
### Step 1.2 — Lock the concept document
|
||
|
||
```
|
||
Produce a complete concept document covering:
|
||
auth, roles, data model decisions, core user flows, edge cases,
|
||
notifications, export requirements, and anything deferred to a later phase.
|
||
Present it as a visual summary. Flag any remaining open questions.
|
||
```
|
||
|
||
Do not proceed until every open question is answered.
|
||
|
||
---
|
||
|
||
### Step 1.3 — Define the design system
|
||
|
||
```
|
||
Here are my brand assets: [attach files]
|
||
The app needs light and dark mode.
|
||
Primary users will be on [mobile / desktop / both].
|
||
Produce a design system covering:
|
||
- CSS variables for all colours (brand + status colours)
|
||
- Logo usage rules for light and dark mode
|
||
- Typography choices
|
||
- Any language toggle requirements
|
||
Show me a preview of light and dark mode side by side.
|
||
```
|
||
|
||
---
|
||
|
||
### Step 1.4 — Produce the three project files
|
||
|
||
```
|
||
Produce three files for this project:
|
||
|
||
1. CLAUDE.md — the project anchor file. Covers: stack, roles,
|
||
data model rules, key business logic, design system (colours,
|
||
fonts, logo rules, CSS variables), UI rules, and project structure.
|
||
Claude Code and Codex read this at the start of every session.
|
||
|
||
2. TASKS.md — a numbered build checklist, one task per session,
|
||
ordered by dependency. Each task includes: which tool to use,
|
||
the exact session prompt, and a checklist of deliverables.
|
||
Include Phase 1 (core build) and stub out Phase 2.
|
||
|
||
3. A stakeholder document in [German/English] — plain language, no code.
|
||
Covers: the problem, the solution, every feature with its reasoning,
|
||
the technical approach in one paragraph, and a phased roadmap.
|
||
Suitable for presenting to a non-technical audience.
|
||
```
|
||
|
||
---
|
||
|
||
## Phase 2 — Setup
|
||
|
||
**Goal:** Initialise the project on your machine.
|
||
|
||
Run once, before any coding sessions begin.
|
||
|
||
```fish
|
||
# Create project folder
|
||
mkdir ~/projects/your-app-name
|
||
cd ~/projects/your-app-name
|
||
|
||
# Copy in the three documents from Phase 1
|
||
cp ~/Downloads/CLAUDE.md .
|
||
cp ~/Downloads/TASKS.md .
|
||
cp ~/Downloads/logo-signet.png . # if applicable
|
||
|
||
# Initialise git
|
||
git init
|
||
git add .
|
||
git commit -m "chore: initial concept documents"
|
||
|
||
# Create virtual environment
|
||
python -m venv venv
|
||
source venv/bin/activate.fish
|
||
|
||
# Create .env (never commit this)
|
||
touch .env
|
||
echo ".env" >> .gitignore
|
||
echo "*.db" >> .gitignore
|
||
echo "__pycache__/" >> .gitignore
|
||
echo "*.pyc" >> .gitignore
|
||
echo "venv/" >> .gitignore
|
||
|
||
git add .gitignore
|
||
git commit -m "chore: gitignore"
|
||
```
|
||
|
||
**Minimal `.env` for any Flask + SQLite + Flask-Mail project:**
|
||
|
||
```ini
|
||
FLASK_APP=run.py
|
||
FLASK_CONFIG=development
|
||
SECRET_KEY=generate-with-python-c-import-secrets-print-secrets.token_hex-32
|
||
MAIL_PASSWORD=your-mail-password
|
||
MAIL_SUPPRESS_SEND=True # remove this in production
|
||
```
|
||
|
||
---
|
||
|
||
## Phase 3 — Core Build (Phase 1 sessions)
|
||
|
||
**Goal:** Build the working app, one session at a time.
|
||
|
||
### Before every session
|
||
|
||
1. Open `TASKS.md` — find the next unchecked session
|
||
2. Read the deliverables — understand what done looks like
|
||
3. Choose your tool:
|
||
|
||
| Use Claude Code / Codex CLI when | Use Continue + Qwen when |
|
||
|---|---|
|
||
| Creating multiple new files | Editing one specific file |
|
||
| Wiring up the whole app | Adding a single route or function |
|
||
| Cross-file refactoring | Fixing a bug |
|
||
| First session (scaffold) | All implementation sessions |
|
||
|
||
### Claude Code session
|
||
|
||
```fish
|
||
cd ~/projects/your-app-name
|
||
claude
|
||
```
|
||
|
||
Paste the session prompt from `TASKS.md`. Claude Code reads `CLAUDE.md` automatically.
|
||
|
||
### Codex CLI session
|
||
|
||
```fish
|
||
cd ~/projects/your-app-name
|
||
codex
|
||
```
|
||
|
||
Same session prompt. Codex also reads `CLAUDE.md` if you instruct it to at the start:
|
||
|
||
```
|
||
Read CLAUDE.md first. Then: [paste session prompt]
|
||
```
|
||
|
||
### Continue session (Qwen — writing code)
|
||
|
||
```fish
|
||
llama-switch # pick Coder
|
||
code ~/projects/your-app-name
|
||
```
|
||
|
||
New chat (`Ctrl+L` → `+`), then:
|
||
|
||
```
|
||
@file app/[relevant-file].py
|
||
@file CLAUDE.md
|
||
|
||
[Paste session prompt from TASKS.md]
|
||
```
|
||
|
||
### Review after every core session (Mistral)
|
||
|
||
```fish
|
||
llama-switch # pick Architect
|
||
```
|
||
|
||
New chat:
|
||
|
||
```
|
||
@file app/[file-you-just-wrote].py
|
||
@file CLAUDE.md
|
||
|
||
Review this against CLAUDE.md.
|
||
Correctness issues first, then anything that will break
|
||
when integrated with related files.
|
||
Do not rewrite — flag issues as a numbered list.
|
||
```
|
||
|
||
### Inline fix (Qwen · Ctrl+I)
|
||
|
||
Highlight code → `Ctrl+I`:
|
||
|
||
```
|
||
[One sentence describing the change]
|
||
```
|
||
|
||
Accept: `Ctrl+Shift+Enter` — Reject: `Escape`
|
||
|
||
### After every session
|
||
|
||
```fish
|
||
git add .
|
||
git commit -m "feat: session [N] — [short description]"
|
||
```
|
||
|
||
Check off every deliverable in `TASKS.md` before starting the next session.
|
||
|
||
---
|
||
|
||
## Phase 4 — Feature Expansion (Phase 2 sessions)
|
||
|
||
**Goal:** Add features on top of a working foundation.
|
||
|
||
Same session discipline as Phase 3. Each feature is a mini-cycle:
|
||
|
||
```
|
||
Audit → Plan → Build → Review → Commit
|
||
```
|
||
|
||
### Audit prompt (run first, before any build session)
|
||
|
||
```
|
||
Read CLAUDE.md.
|
||
I want to add [feature name].
|
||
Audit the current codebase for what already exists that is relevant.
|
||
Tell me:
|
||
- What files will need to change?
|
||
- What already exists that I can build on?
|
||
- What are the risks or dependencies?
|
||
- What order should I tackle this in?
|
||
Do not write any code. Diagnosis only.
|
||
```
|
||
|
||
### Build prompt template
|
||
|
||
```
|
||
Read CLAUDE.md.
|
||
I am implementing [feature name].
|
||
Relevant existing files: [list them]
|
||
|
||
Task: [specific thing to build this session]
|
||
State your approach and which files you will touch before writing anything.
|
||
One piece at a time — start with [data model / logic / route / template].
|
||
```
|
||
|
||
---
|
||
|
||
## Phase 5 — AI Tool Comparison
|
||
|
||
**Goal:** Run Claude Code and Codex on the same task to compare output quality.
|
||
|
||
### Setup
|
||
|
||
```fish
|
||
# Clone the repo twice into separate folders
|
||
git clone your-repo-url room-booking-claude
|
||
git clone your-repo-url room-booking-codex
|
||
|
||
# Create a comparison branch in each
|
||
cd room-booking-claude && git checkout -b compare/claude-code
|
||
cd ../room-booking-codex && git checkout -b compare/codex
|
||
```
|
||
|
||
### Give both the same task
|
||
|
||
Use the same session prompt verbatim. Do not adjust it between tools.
|
||
|
||
### Scoring rubric
|
||
|
||
After each tool completes the task, score it:
|
||
|
||
| Criterion | What to look for |
|
||
|---|---|
|
||
| Correctness | Does it follow the business rules in CLAUDE.md exactly? |
|
||
| Completeness | Are all deliverables produced without prompting? |
|
||
| Code quality | Is it readable, consistent with existing style? |
|
||
| Context adherence | Did it touch files it was told not to touch? |
|
||
| Autonomy | How many clarifying questions did it ask mid-task? |
|
||
|
||
Score each 1–5. Keep notes. After 3–4 sessions you will have a clear picture of which tool suits your workflow better.
|
||
|
||
---
|
||
|
||
## Prompt Library
|
||
|
||
### Concept phase
|
||
|
||
**Start a new idea:**
|
||
```
|
||
I want to build [description]. Let's work through the concept
|
||
before any code is written. Ask me one question at a time.
|
||
```
|
||
|
||
**Lock a decision:**
|
||
```
|
||
Summarise what we have agreed on so far and list any remaining
|
||
open questions before we move on.
|
||
```
|
||
|
||
### Build phase
|
||
|
||
**Plan before writing:**
|
||
```
|
||
Read CLAUDE.md.
|
||
Task: [description]
|
||
Before writing anything, state your approach and which files you will touch.
|
||
```
|
||
|
||
**One piece at a time:**
|
||
```
|
||
Good. Now write only the [data model / service layer / route / template].
|
||
Nothing else yet.
|
||
```
|
||
|
||
**Bug diagnosis:**
|
||
```
|
||
@currentFile
|
||
Line [N] throws [error] when [condition].
|
||
Root cause first, then minimal fix, then any follow-up improvements.
|
||
Do not ask for other files unless you explain exactly why you need them.
|
||
```
|
||
|
||
**Explain unfamiliar code:**
|
||
```
|
||
@file src/some-file.py
|
||
Walk me through what this file does step by step.
|
||
Assume I have not seen this codebase before.
|
||
Focus on: what it does, why it is written this way, any gotchas.
|
||
Keep it under 10 lines.
|
||
```
|
||
|
||
**Refactor safely:**
|
||
```
|
||
@currentFile
|
||
Refactor this one step at a time.
|
||
Explain what you are changing and why before each step.
|
||
Do not touch anything outside the highlighted section.
|
||
```
|
||
|
||
**Review finished component:**
|
||
```
|
||
@file [component]
|
||
@file CLAUDE.md
|
||
Review this against CLAUDE.md.
|
||
Correctness first, then maintainability concerns.
|
||
Do not rewrite — flag issues as a numbered list.
|
||
```
|
||
|
||
**Stuck on approach:**
|
||
```
|
||
@file CLAUDE.md
|
||
I need to implement [X].
|
||
Give me 2–3 approaches, pros and cons of each, then your recommendation.
|
||
```
|
||
|
||
---
|
||
|
||
## The Five Rules
|
||
|
||
1. **New session per task** — never carry context across tasks
|
||
2. **Always attach files explicitly** — never assume the model knows what you are looking at
|
||
3. **Plan before you build** — agree on the approach before any code is written
|
||
4. **One piece at a time** — data model, then logic, then route, then template
|
||
5. **Architect reviews every core component** — never skip the review step on models, auth, and business logic
|
||
|
||
---
|
||
|
||
## Quick Reference
|
||
|
||
```fish
|
||
Start Claude Code: cd ~/project && claude
|
||
Start Codex: cd ~/project && codex
|
||
Start Continue chat: Ctrl+L → click +
|
||
Inline edit: Highlight code → Ctrl+I
|
||
Accept inline: Ctrl+Shift+Enter
|
||
Reject inline: Escape
|
||
Switch local model: llama-switch
|
||
Commit after session: git add . && git commit -m "feat: session N — description"
|
||
Generate secret key: python -c "import secrets; print(secrets.token_hex(32))"
|
||
```
|