Developer Switches from Specs to Proposals for Parallel Claude Code Sessions

The Problem with Specs-First Approach

The developer encountered issues where writing detailed specifications upfront led to AI-generated code that was technically correct but contextually wrong. The spec would say "add rate limiting to auth endpoints" but wouldn't include context about previously rejected approaches (like token buckets) or implementation decisions (like choosing Redis over Cloudflare for staging). This created situations where the AI would make reasonable choices that reopened already-closed decisions.

Updating specs became its own mini-project, and by the time updated specs were reviewed, the codebase had already drifted. The spec captured the "what" but lost the "why"—all the reasoning, rejected alternatives, and timing of decisions were missing.

The Proposal-First Alternative

Instead of writing specs upfront and coding to match them, the developer writes proposals—short documents that capture why a change is happening, what was considered and rejected, and what's in or out of scope. The spec gets updated after the code lands to reflect what was actually built.

Example comparison:

• A spec says: "The system shall support rate limiting."
• A proposal says: "Brute-force attacks detected on prod. Adding rate limiting via sliding window + Redis (Cloudflare not available in staging). Rejected token bucket because of burst traffic issues. Scope: login + password reset only."

The proposal gives the AI (and future developers) the full picture.

Parallel Proposals Workflow

The developer runs multiple Claude Code sessions simultaneously, each working on a different proposal. Sometimes they create competing proposals solving the same problem from different angles.

Typical workflow:

• Working on 2-3 features/bugs/issues at the same time
• Creating 1 or 2 proposals for different approaches per issue
• Spinning up Claude Code sessions for each proposal to run in parallel
• Each session produces a GitHub PR
• GitHub PRs serve as the proposal review platform
• Reviewing approach and code together
• If two proposals tackle the same problem differently, picking the better one and closing the other
• Once approved PRs land, telling Claude to implement the proposals
• Updating the spec to reflect code changes for quick reference in future proposals

The spec becomes a living document that always matches reality instead of an aspirational document that drifts from day one.

PACE Cycle

The developer calls this cycle PACE (to remember the steps):

• Propose: Write a short proposal with context and reasoning
• Approve: Review on GitHub PR, approach (approve, revise, reject)
• Code: AI implements exactly what was proposed, nothing more
• Evolve: Update the spec to reflect the new reality