# 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))"
```
