Skip to content

Explore → Plan → Code → Commit

The core workflow that prevents Claude from jumping to solutions that introduce inconsistency or technical debt.

Why This Workflow

Without structure, Claude tends to:

  • Start coding immediately without understanding existing patterns
  • Introduce inconsistent styles across the codebase
  • Miss architectural constraints mentioned in other files
  • Produce code that works but doesn't fit the project

The Explore → Plan → Code → Commit workflow prevents all of these.

Step 1: Explore (Don't Code Yet)

Read the files in src/auth/ and understand how we currently handle user sessions.
Look at the patterns used. Don't write any code yet.

What to Explore

  • Existing implementations of similar features
  • Related test files for patterns and expectations
  • Schema definitions and API contracts
  • CLAUDE.md and project conventions

Tips

  • Use the Explore subagent for large codebases — it keeps your main context clean
  • Be specific about which directories to read
  • Explicitly say "don't write any code yet"

Step 2: Plan

Plan how to add OAuth2 support while maintaining consistency
with our existing session handling. Create a written plan. Don't implement yet.

What the Plan Should Include

  • Which files to modify and create
  • Which patterns to follow (reference specific files)
  • Task breakdown with dependencies
  • Tests to write
  • Potential risks or breaking changes

Review the Plan

Before proceeding, review Claude's plan:

  • Does it follow existing patterns?
  • Are the right files being modified?
  • Is the scope appropriate (not over-engineered)?
  • Are there tests for each change?

Ask Claude to adjust if needed:

The plan looks good but we should also update the OpenAPI docs.
Add that as a step.

Step 3: Implement Against the Plan

Implement step 1 from the plan. Follow the existing patterns in src/auth/.
Run tests after the change.

Implementation Rules

  1. One step at a time — don't batch multiple steps
  2. Test after each step — catch issues early
  3. Follow the plan — don't improvise unless something is clearly wrong
  4. Reference patterns — remind Claude which files to follow

After each step:

Implement step 2. Run tests.

Step 4: Commit and Document

Use the commit skill to generate a conventional commit message:

/sq-dev:make-commit

For larger features, create a PR:

Create a PR with a summary of what changed and why.
Link it to issue #42.

Workflow Variants

Test-Driven Development (TDD)

For critical features with clear acceptance criteria:

  1. "Write tests for the OAuth2 flow based on these criteria: [list]. Don't implement yet."
  2. "Run the tests and confirm they fail."
  3. "Commit the tests."
  4. "Implement code to pass the tests. Don't modify the tests."
  5. "Commit the implementation."

Writer/Reviewer Pattern

For important changes, use two Claude sessions:

  • Session 1: Writes the code
  • Session 2 (fresh context): Reviews the code without bias toward its own work

This catches issues a single session might miss due to confirmation bias.

Fast Track

For trivial changes (typo fix, config update):

Fix the typo in src/auth/router.py line 42 — "authetication" should be
"authentication". Commit with message "fix(auth): fix typo in router".

Skip the full workflow when the change is obvious and low-risk.

Real Example: Adding a CRUD Resource

Explore

Read src/users/ to understand how the users domain is structured.
Look at router.py, schemas.py, models.py, service.py, and the tests.
Don't write any code yet.

Plan

Plan how to add a "projects" domain following the exact same
patterns as "users". Create a plan with all files to create and modify.

Plan output:

  1. Create src/projects/models.py — SQLAlchemy model following src/users/models.py
  2. Create src/projects/schemas.py — Pydantic schemas following src/users/schemas.py
  3. Create src/projects/service.py — Business logic following src/users/service.py
  4. Create src/projects/router.py — CRUD endpoints following src/users/router.py
  5. Create src/projects/dependencies.py — DI functions
  6. Register router in src/main.py
  7. Create Alembic migration
  8. Create tests/projects/ following tests/users/ patterns

Implement

Implement step 1 — create the Project model. Run tests.

Implement step 2 — create the Pydantic schemas. Run tests.

(Continue through all steps)

Commit

/sq-dev:make-commit

Then create a PR linking to issue #15.