Skip to content
Docs

Design and Build mode

Design and Build mode are the two states a Denote project can be in. They control what CLAUDE.md says, which controls how Claude Code behaves in this folder. Design mode sets Claude up as a thinking partner. Build mode hands the file over to you so Claude Code is free to write code. Flip between them from the top bar.

Why two modes

Claude Code reads CLAUDE.md at the start of every session. That single file decides whether Claude is in "help me think about the design" mode or "help me build the app" mode.

  • Design-mode CLAUDE.md — tells Claude not to write code, to only edit design/*.json, to ask questions, to think in objects and workflows.
  • Build-mode CLAUDE.md — yours. Tells Claude there's a finished design under design/, here's where to find it, go build the app.

Both versions live at CLAUDE.md in the project root because that's the path Claude Code reads. Denote swaps the file when you toggle.

Where you see it

  • Mode chip in the top bar — right-side header, next to the activity hub. Design mode = muted lightbulb. Build mode = red Hammer + Build mode label (unmissable on purpose).
  • Build-mode banner on the terminal — red strip pinned to the bottom of the embedded terminal: "Claude won't be a design partner in Build Mode" with a Switch button.
  • Spec layer status line — a muted single line under the Spec title states which mode you're in.

What happens when you toggle

Clicking Switch opens a confirmation dialog. Confirming runs:

  1. Save the current CLAUDE.md. If leaving build mode, Denote copies the file into .denote/CLAUDE.user.md so your edits travel with you.
  2. Write the new CLAUDE.md. Entering design mode → regenerates the design-partner version (preserves your ## Custom Rules section). Entering build mode → restores your previous build-mode file from snapshot, or writes a minimal starter if first time.
  3. Restart the embedded terminal. Claude Code only reads CLAUDE.md when its session starts. Without restart, the running session keeps the old rules. The dialog warns your current Claude conversation will end.

What survives across toggles

  • Build-mode CLAUDE.md — everything in it. Coding conventions, framework prefs, project context. Denote treats it as yours, not its.
  • Design-mode CLAUDE.md — mostly Denote-managed, but has a ## Custom Rules marker. Anything below the marker is preserved on regeneration. Anything above is overwritten.
  • Design files under design/ — never touched by a mode toggle.

What changes and what doesn't

Design mode Build mode
CLAUDE.md at project root Denote-managed thinking-partner template Yours to write freely
What Claude Code can do in the terminal Edit design/*.json, ask questions, refuse to write code Anything you ask, including writing code
Denote's canvas + layer panels Fully usable Fully usable
Design files under design/ Edit in Denote or by hand Edit in Denote or by hand
Top-bar mode chip Muted lightbulb Red Build mode chip
Terminal banner Hidden Red strip at bottom

The canvas works in either mode. The toggle only affects Claude Code in the terminal.

When to switch

  • Stay in design mode while you're moving through Vision → Ontology → Architecture → Screens; while you're running skills in the terminal; while you're talking through architecture with Claude.
  • Switch to build mode when you're ready to open the project in VS Code, point Claude Code at it, and start writing the app. Everything stays in this folder; nothing moves.
  • Switch back to design mode any time you want to revisit a layer or think through a new direction.

Two open caveats

  • The toggle doesn't retroactively fix a running session. If Claude has already been chatting with you in build mode and you flip to design, Denote restarts the terminal so the next session reads the new rules. The previous conversation is gone. The dialog warns you.
  • Custom rules in design-mode CLAUDE.md are only preserved below the marker. Above the marker gets overwritten on regeneration. Build-mode CLAUDE.md is yours entirely; design-mode is Denote-managed except below the marker.

Where to next