claude-code - 💡(How to fix) Fix [FEATURE] Architect Mode — Pre-Execution Architectural Planning Layer for Claude Code

Preflight Checklist

• I have searched existing requests and this feature hasn't been requested yet
• This is a single feature request (not multiple features)

Problem Statement

Claude Code's mode hierarchy has a gap. The current modes map cleanly to execution concerns:

This works well once you know what you're building and how you want to build it. But there's a layer above that is currently unserved inside CC:

"I know the purpose of what I want to build, but I need to explore the solution space — help me lock down the approach before any execution starts."

That is not Plan Mode. Plan Mode presupposes the approach has already been chosen. It answers "which files do I touch and in what order?" It does not answer "should we use an event-driven architecture or direct service calls, and what are the downstream implications of each?"

Today, when a technical lead needs to do upstream thinking — explore approaches, weigh trade-offs, produce an ADR, map a roadmap — they must leave CC entirely. The decision-making that should constrain and inform execution happens outside CC, in a separate tool, in a separate context, and then must be manually re-introduced. The result is a seam in the workflow exactly where coherence matters most.

Proposed Solution

A new harness-level mode: Architect Mode (--mode architect or /architect). Not a prompt nudge, not a CLAUDE.md directive, not a skill — a mode with different default affordances than Plan or Execute.

Ideal User Experience

The developer enters Architect Mode at the start of a non-trivial feature or refactor, before any files are touched:

$ claude --mode architect

Or from within a session:

/architect

CC reads the codebase but cannot write to source or config files. The only writable surface is a planning artifacts directory (docs/adr/, docs/roadmap/, docs/specs/, or a configurable path). The conversation is oriented around exploring the solution space, not producing code.

The developer and CC work through questions like: What are the viable approaches? What does the existing codebase constrain? What decision needs to be locked down before implementation begins? CC produces structured artifacts — ADRs, roadmaps, dependency maps — directly into the repo as versioned documents.

When the approach is settled, the developer runs:

/handoff

CC produces a structured summary artifact and transitions to Plan Mode, with the ADRs and roadmap available as upstream constraints for the plan. Plan Mode sessions can load these artifacts and treat them as settled decisions rather than re-litigating them.

Permission Model

File editing is disabled at the harness level — not as a behavioral instruction that can drift, but as a structural guarantee. The value of this constraint is trust: the developer knows that entering Architect Mode cannot accidentally change anything.

Natural Deliverables

• ADRs — "we chose X over Y because Z" — captured proactively, version-controlled in the repo, loadable by future Plan Mode sessions
• Roadmaps — sequenced milestones that become the scope boundaries of individual Plan Mode sessions
• Problem / solution framing docs — the "why we're building this" that keeps execution plans honest
• Dependency maps — what has to exist before what else can be planned

The Full Pipeline

Architect Mode  →  produces planning artifacts (ADRs, roadmaps, specs)
                              ↓
                 Plan Mode reads them as upstream constraints
                              ↓
                       Plan Mode  →  produces execution plans
                              ↓
                        Execute  →  produces code

Each layer's output constrains the next. A roadmap with discrete milestones can directly seed Plan Mode sessions — one milestone per plan.

Alternative Solutions

Currently: Claude.ai Projects as a substitute

Many CC users — myself included — use Claude.ai Projects as a workaround for this layer. A Project can hold cross-cutting context, prior decisions, and strategic conversations. It partially works. But using it as an architectural planning layer for active CC work creates a persistent synchronization problem:

• The codebase is in CC, not Claude.ai. Architectural decisions made in Claude.ai are made without direct read access to what actually exists in the repo — existing patterns, prior decisions embedded in code, accumulated tech debt. ADRs written there are grounded in conversation and memory, not in actual codebase state.
• Artifacts live in the wrong place. An ADR written in a Claude.ai Project lives in that Project — not in the repo, not version-controlled alongside the code it governs, not loadable by Plan Mode sessions.
• Every session requires manual re-bridging. The developer summarizes what was decided in Claude.ai, pastes it into CC, and hopes the framing survives the translation. This is where strategic intent gets lost.
• Context splits across tools. Architectural reasoning and execution reasoning live in different products, different contexts, different memory scopes. The handoff is copy-paste, not structured artifact. Claude.ai is the right home for user-centric knowledge — preferences and context that span many projects. Architect Mode is the right home for project-centric architectural thinking — decisions that belong in the repo, grounded in the actual codebase, with a direct path into Plan Mode.

CLAUDE.md behavioral nudges

CLAUDE.md can shift tone and defaults — "before editing files, propose an approach and wait for confirmation" — which gets behaviorally closer. What it cannot do:

• Disable file editing at the harness level (a behavioral nudge is not a structural guarantee)
• Change CC's implicit framing that the goal is code on disk
• Provide a clean exit-to-Plan-Mode transition with captured state
• Elevate document-writing as the primary affordance rather than an afterthought CLAUDE.md gets approximately 60% of the desired behavior. A real mode provides the remaining 40%: harness-level guarantees, different defaults, and an unambiguous handoff.

Patching Plan Mode

Several existing issues (#30438, #14728, #29445) approach this by extending Plan Mode upward — adding persistence, richer structure, or goal tracking. These are valuable improvements, but they don't close the gap. Plan Mode presupposes an approach has been chosen. Architect Mode is for before that choice is made.

Priority

Medium - Would be very helpful

Feature Category

Interactive mode (TUI)

Use Case Example

Scenario: Adding real-time collaboration to an existing single-user editor. The feature is non-trivial — it touches persistence, conflict resolution, and potentially the entire session model. The approach isn't obvious.

Without Architect Mode (current workflow):

1. Open a Claude.ai Project. Start describing the feature and asking for architectural options.
2. Claude.ai has no access to the codebase. Suggestions are generic — based on the description, not on what actually exists.
3. After some back-and-forth, a rough direction emerges. Write notes manually.
4. Switch to CC. Paste a summary of what was decided. Hope the framing is complete enough.
5. CC reads the codebase and immediately suggests implementation approaches that contradict what was just decided in Claude.ai — because it's seeing constraints for the first time.
6. Re-litigate the approach inside CC. The Claude.ai conversation is now stale and out of sync.
7. Eventually start Plan Mode with an approach that was arrived at through friction, not clarity.

With Architect Mode:

1. claude --mode architect from the repo root.
2. "I'm adding real-time collaboration. Walk me through the viable approaches given what's already here."
3. CC reads the codebase. Points out that the existing session model uses optimistic local state — which constrains the conflict resolution options significantly. This would not have surfaced in Claude.ai.
4. Two approaches are explored. One is eliminated because it requires refactoring the persistence layer, which is out of scope. That decision is written to docs/adr/001-realtime-sync-strategy.md directly in the repo.
5. A milestone roadmap is written to docs/roadmap/realtime-collab.md — three milestones, each scoped tightly enough to hand off to Plan Mode.
6. /handoff — CC produces a summary and transitions to Plan Mode with the ADR and roadmap available as upstream context.
7. Plan Mode loads the ADR. The approach is already settled. The plan is about implementation, not re-litigating architecture. The difference is not just convenience — it's that the architectural decision was made with full codebase context, captured in a versioned artifact, and handed to Plan Mode without manual translation.

Additional Context

Related issues (not duplicates)

Existing multi-agent orchestration (Agent Teams, Task tool subagents) is also horizontal — coordinating agents doing execution work in parallel. Architect Mode is vertical: it sits upstream of execution entirely and hands downward.

The pattern this mirrors

This is a pattern familiar to any technical lead: the decision-making layer that constrains what gets built is the most expensive layer to re-litigate. Getting it right before execution starts — and capturing it in artifacts that survive context resets — is qualitatively different from planning how to execute. CC is the right home for this work. Right now it has no place for it.