Skip to content

gpsaggese/helpers / .claude/skills/architecture.write_design

architecture.write_design

Verified

Write the design docs of a project from its PRD, before the code

Goal

  • Given a PRD (Product Requirement Document), write docs/02-design.architecture.md and docs/02.<N>-design.<component>.md per component
  • Design before the code exists: do not write code

Input

  • <PRD>: the PRD file, e.g., docs/01-prd.md
  • <DOCS_DIR>: the docs/ dir of the project, optional
    • If missing, use the dir of <PRD>

Workflow

Read the Inputs

  • Read <PRD> and the existing docs in <DOCS_DIR>
  • Read the existing code and docs that the design must fit
  • Read .claude/skills/architecture.rules.md and .claude/skills/C4.rules.md

Ask If the PRD Is Unclear

  • If a requirement is ambiguous or two requirements conflict:
    • Do not guess
    • Ask the user and wait for the answers

Split Into Components

  • Propose components, each with one responsibility
  • Respect the layering rules in .claude/skills/architecture.rules.md
  • Show the proposal and wait for user confirmation before writing the docs

Write the Overview

  • Create <DOCS_DIR>/02-design.architecture.md
  • Follow the template .claude/templates/project_design.template.md
  • Show the context and containers with a PlantUML C4 diagram, per .claude/skills/C4.rules.md
  • Map each requirement R<N> of the PRD to its component
    • Link each R<N> to its H3 in the PRD, per .claude/skills/project.rules.md section "Link Requirements and Decisions"

Write One Doc per Component

  • Create <DOCS_DIR>/02.<N>-design.<component>.md for each component
  • Follow .claude/skills/project.rules.md section "Write a Design Doc" and the template .claude/templates/project_design.template.md
  • Record each non-obvious choice in <DOCS_DIR>/03-decisions.md, following the template .claude/templates/project_decisions.template.md
    • Create the file if it does not exist
  • Link each decision from the design docs that follow it, per .claude/skills/project.rules.md section "Link Requirements and Decisions"

Update the Index

  • Add a row for each new doc to <DOCS_DIR>/README.md, if the file exists

Conventions

  • Follow .claude/skills/project.rules.md for the docs of a project
  • Follow .claude/skills/architecture.rules.md for layering and interfaces
  • Follow .claude/skills/markdown.rules.md and .claude/skills/text.rules.md
  • Say in each file that you create how it was generated, with this line right after the title:
    - Generated by `.claude/skills/architecture.write_design/SKILL.md`
    

Constraints

  • Do not implement any code
    • Short snippets (a class interface, a schema, a function signature) are fine
  • Do not use this skill to document an existing Python file: use .claude/skills/readme_file.write_architecture/SKILL.md
  • Do not commit any change

Verification

  • Every requirement of the PRD maps to a component
  • Every component has one responsibility and one design doc
  • The overview has a PlantUML C4 diagram
  • No design doc has a Mermaid C4 diagram
  • Every non-obvious choice is in 03-decisions.md
  • Every requirement id and decision id in a design doc is a link to its H3
  • No design doc contains full implementation code
  • Each file that you create says that it was generated by .claude/skills/architecture.write_design/SKILL.md
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 318kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 196kUpdated Claude CodeCodexVerifiedInstall