Claude Code Design
Design Claude Code prompts and environments for production delivery projects. This Skill produces paste-ready artifacts — CLAUDE.md drafts, agent topology recommendations, scope-authorization frameworks, halt-and-escalate triggers, Skills/Hooks/MCP plans, and chat-to-Code handoff specifications. The methodology is grounded in tested patterns from a production CC deployment 2026-05-04 (27/27 ship, 18-WI evolution arc), Anthropic primary documentation, and named practitioner consensus (rosmur, obra/superpowers, alexop.dev, Shrivu Shankar, Marc Nuri).
This Skill operates in both chat-based design conversations (CP) and Claude Code (CC). In CP, it focuses on DESIGN, EVOLVE, RESEARCH, and TEMPLATE modes — design conversations, brainstorming, scaffolding, cross-project synthesis. In CC, the same modes work alongside REMEDIATE — the closed-loop mode that consumes a HYGIENE_REPORT.md produced by rootnode-repo-hygiene and produces (then executes, after explicit user acceptance) an EXECUTION_PLAN.md against the actual repo.
The Skill produces design artifacts in all modes. REMEDIATE mode is the only mode that also executes — and only its Phase 2, gated by an explicit user acceptance step that follows Phase 1 plan generation.
Important
Source discipline is non-negotiable. Every substantive claim about Claude Code behavior, MCP capability, or agent design pattern carries an inline source tag — [Anthropic docs], [<project> §X], [practitioner: name + artifact], or [speculation]. Tier 5 community sources are signal-only, never authoritative. See references/source-grading-and-tagging.md for the full hierarchy.
Generalizable vs. project-specific tagging. Every pattern drawn from a production CC deployment or other working examples is tagged inline as [generalizable], [project-specific], or [generalizable structure, project-specific content] with a one-line basis for the tag. Default to "may be project-specific until proven otherwise." See references/source-grading-and-tagging.md.
Tool/agent gap discipline. Never recommend a tool, MCP server, agent role, Skill, or hook without identifying the specific operational gap it fills. "Adding X for completeness" is anti-pattern. The question is always: what concrete failure mode does this address, and is that failure mode actually present in the user's situation?
The 7-layer placement rule comes first. Before specifying CLAUDE.md content, place each piece of content in the correct mechanism (CLAUDE.md / rules / Skills / subagents / hooks / MCP / settings). Misplaced content is the single most common cause of agent unreliability. See references/cc-environment-design-patterns.md.
Halt-and-escalate triggers are mandatory. Every DESIGN MODE deployment plan and every EVOLVE MODE update specifies explicit halt-and-escalate triggers. Autonomous CC iteration without halt triggers is the failure mode that produces the worst outcomes.
Output complete files. Per the user's working preference: produce complete files (CLAUDE.md, agent specs, design briefs), never diffs or partial sections — except in EVOLVE MODE where the existing file is in context and a section-level delta is the deliverable.
How to Use This Skill
Step 1 — Determine the mode
Five modes. Mode is inferred from the request signal; confirm in one line at the start of the response, then proceed. Some modes have natural surfaces (CP vs CC) but all 5 work in both — surface emphasis is a tendency, not a constraint.
| Mode | Trigger signals | Output | Natural surface |
|---|---|---|---|
| DESIGN | "design CC for X", "build CC environment for Y", "scaffold a Claude Code repo", new project scaffolding | Complete deployment plan: CLAUDE.md draft + initial prompt + agent topology + scope rules + halt triggers + handoff point + runtime tooling recommendations | CP for greenfield (no repo yet); CC for in-repo new work (new module, new service inside existing repo) |
| EVOLVE | "we hit X friction in [project]", "the agent keeps doing Y", "this pattern emerged across sessions", "we need to add Z to existing CLAUDE.md" | Section-level deltas to existing artifacts: CLAUDE.md updates as inserts/replacements, new agent specs, new scope rules, change-log entry template, regression-sweep specification | Both — speculative friction in CP; in-repo friction in CC where the deltas can be applied directly |
| RESEARCH | "should we adopt X", "is Y worth using", "what's the landscape for Z", "what tool fills the gap of W" | Structured assessment: gap definition, candidates with source class, fit analysis, decisive recommendation, speculative notes | CP-leaning (web search heavy; polluting a delivery repo's CC session is anti-pattern) |
| TEMPLATE | "give me a CLAUDE.md skeleton for X-class projects", "build a reusable prompt template", "produce an agent role template I can reuse" | Complete template with placeholders in {BRACKETED_CAPS} + usage notes + filing recommendation | CP-leaning (cross-project synthesis is wrong context inside one delivery's CC) |
| REMEDIATE | "remediate the hygiene findings", "fix the audit issues", "close the loop on the report", HYGIENE_REPORT.md exists in repo and user invokes this Skill without naming a different mode | Phase 1: EXECUTION_PLAN.md written to repo (steps + validation per step + summary + addressed-findings list). User reviews and explicitly accepts via one of three approval forms (blanket / fragmented / conditional). Phase 2: Skill executes the accepted plan step-by-step, validates each step, halts on failure | CC-native (must read HYGIENE_REPORT.md from repo; Phase 2 writes to repo). CP-only invocation requires pasted findings and produces plan without executing |
Step 2 — Check for or generate the design brief
The Skill operates from a structured design brief for the delivery project. The brief captures: mission, current state, tech surface, governance state, runtime tooling state, authority constraints, verification surface, and known friction. It lives at {project_code}_design_brief.md in the delivery project's KFs (or filesystem if working at the repo level).
On first invocation in a new project: conduct the 5-question interview (mission / current state / tech surface / authority constraints / verification surface), serialize to brief format, offer as a downloadable artifact, and recommend adding to the delivery project's KFs. See references/cc-methodology-patterns.md §"The design brief workflow" for the full interview script and brief format.
On subsequent invocations: read the existing brief as input. If the brief is stale (front-matter last_updated > 90 days, or current state field is wrong), surface this and offer to refresh.
If brief generation is over-investment for the request: small focused asks (one CLAUDE.md section, one prompt rewrite, one agent spec review) can proceed without a brief. Use judgment — the brief exists to ground multi-faceted design work, not to bottleneck simple tasks.
Step 3 — Apply mode-specific reasoning
Read the relevant references before producing output. Each mode draws from a specific subset:
- DESIGN MODE consults: cc-methodology-patterns, cc-environment-design-patterns, cc-skills-and-hooks-composition, chat-to-code-handoff-patterns. Optional: cc-prompt-design-patterns (if the deliverable includes a CC initial prompt or session prompt).
- EVOLVE MODE consults: cc-anti-patterns (diagnose the friction), cc-methodology-patterns (find the relevant pattern), cc-environment-design-patterns or cc-skills-and-hooks-composition (apply the fix at the correct layer).
- RESEARCH MODE consults: source-grading-and-tagging (apply the source authority hierarchy), cc-anti-patterns (verify the candidate doesn't introduce known anti-patterns).
- TEMPLATE MODE consults: cc-methodology-patterns (the structural pattern being templated) and the rele