Skip to content

CLAUDE.md

Latest commit

 

History

History
99 lines (76 loc) · 6.43 KB

CLAUDE.md

File metadata and controls

99 lines (76 loc) · 6.43 KB

iOS MVP Factory

Workflow — The Ralph Loop

This project uses a PM-driven loop for rapidly building MVP iOS apps. The user acts as Product Manager — they define features, priorities, and acceptance criteria. Claude acts as the engineer — implementing, iterating, and shipping.

Loop Steps

  1. Claude reads context — reads CONTEXT.md and BACKLOG.md to pick up where the last iteration left off.
  2. PM provides direction — new features, feedback on the last iteration, or scope changes.
  3. Claude creates a plan — breaks work into tasks, proposes architecture, identifies dependencies. Uses EnterPlanMode for non-trivial apps.
  4. PM reviews & approves — adjusts scope, re-prioritizes, or approves the plan.
  5. Claude creates a feature branch — branches off main with a descriptive name (e.g., feature/tags-system, fix/inbox-sorting). If working in a worktree, open the worktree's .xcodeproj in Xcode so the PM can build and test: open /path/to/worktree/Project.xcodeproj.
  6. Claude implements — builds features incrementally, committing working slices along the way with clear commit messages. After each working slice, update CONTEXT.md with progress so far (what was completed, decisions made, what's next). This preserves progress if the conversation is interrupted mid-iteration.
  7. Claude finalizes context — once all tasks in the iteration are complete, review and clean up the CONTEXT.md entry to reflect the full iteration summary. Commits this update.
  8. PM reviews & tests — provides feedback, files bugs, requests changes. Claude addresses feedback on the feature branch.
  9. PM approves — PM gives explicit approval to merge.
  10. Claude merges to main — merge the feature branch into main.
  11. Repeat — start a new conversation and loop back to step 1. This clears the context window while CONTEXT.md preserves all progress.

Context Window Management

Claude's context window is finite. Without management, long conversations degrade in quality — Claude loses track of earlier details, repeats itself, or makes inconsistent decisions. The Ralph Loop is designed so that CONTEXT.md is always the source of truth, meaning conversations are disposable.

Rules:

  • One iteration = one conversation (ideally). Start a new conversation for each loop iteration.
  • Mid-iteration restart: If an iteration is large and the conversation gets long, Claude should checkpoint CONTEXT.md and tell the PM: "Context is getting long. I've saved progress to CONTEXT.md — start a new conversation to continue."
  • Never lose work: Every working slice commits code + CONTEXT.md update, so a conversation can be dropped at any point without losing progress.

How this works in Claude Desktop (or any chat UI):

  1. Each conversation starts with Claude reading CONTEXT.md and BACKLOG.md — this is how Claude "remembers" prior work.
  2. When an iteration is done (or the conversation is getting long), the PM simply opens a new chat.
  3. In the new chat, Claude picks up exactly where the last conversation left off by reading CONTEXT.md.
  4. The previous conversation can be referenced in the sidebar if needed, but Claude does not depend on it.

How this works in Claude Code (CLI):

  1. Same principle — start a new session (/clear or open a new terminal).
  2. Claude reads CONTEXT.md on startup and resumes from there.
  3. The CLI's auto-compression helps extend conversations, but a fresh session is still preferred between iterations.

Conventions

  • Platform: iOS (Swift / SwiftUI)
  • Min deployment target: iOS 17.0
  • Architecture: MVVM unless the PM specifies otherwise
  • Dependencies: Prefer first-party frameworks (SwiftUI, SwiftData, Observation). Only add third-party deps when justified.
  • Project structure: 
    {AppName}/
├── App/              # App entry point, configuration
├── Models/           # Data models
├── Views/            # SwiftUI views
├── ViewModels/       # View models
├── Services/         # Networking, persistence, business logic
├── Extensions/       # Swift extensions
└── Resources/        # Assets, fonts, etc.

Git Conventions

  • Initialize repo — if the working directory isn't a git repo, git init and create an initial commit before starting work.
  • Branching — each loop iteration works on a feature branch off main. Branch naming: feature/{short-description}, fix/{short-description}, or chore/{short-description}.
  • Commits — commit after each working slice (a complete, testable piece of functionality). Keep commits atomic and messages concise.
    • Format: type: short description (e.g., feat: add tag CRUD and color picker, fix: inbox sort order, chore: update context log)
  • Merging — merge feature branch into main only after PM approval. Use --no-ff to preserve branch history.
  • No force pushes — never rewrite shared history.
  • Context files — CONTEXT.md, BACKLOG.md, and CLAUDE.md changes should be committed as part of the feature branch (not separately to main).

Incremental Context

The running context lives in CONTEXT.md. Claude updates this file incrementally — after each working slice during implementation, and a final cleanup at the end of the iteration. Each update covers: what was built, decisions made, PM feedback, open questions, and what's next. This file is the thread between conversations — read it first, keep it current throughout.

Feature Backlog

The current backlog lives in BACKLOG.md. Format:

## MVP — {App Name}

### P0 (Must Have)
- [ ] Feature description

### P1 (Should Have)
- [ ] Feature description

### P2 (Nice to Have)
- [ ] Feature description

Guidelines for Claude

  • Always read CONTEXT.md and BACKLOG.md before starting work.
  • Implement P0 features first, then P1, then P2.
  • Keep the PM informed at milestones — don't go silent for long stretches.
  • Ask clarifying questions early rather than guessing.
  • Each feature should be a working, testable slice — no half-built screens.
  • Use Xcode previews where practical so the PM can see UI without running the full app.
  • Commit after each working slice — don't batch an entire phase into one commit. Include a CONTEXT.md update with each slice commit.
  • Always verify the repo is in a clean state before starting a new iteration.