gpsaggese/helpers / .claude/skills/architecture.write_design
architecture.write_design
VerifiedWrite the design docs of a project from its PRD, before the code
Goal
- Given a PRD (Product Requirement Document), write
docs/02-design.architecture.mdanddocs/02.<N>-design.<component>.mdper component - Design before the code exists: do not write code
Input
<PRD>: the PRD file, e.g.,docs/01-prd.md<DOCS_DIR>: thedocs/dir of the project, optional- If missing, use the dir of
<PRD>
- If missing, use the dir of
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.mdand.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.mdsection "Link Requirements and Decisions"
- Link each
Write One Doc per Component
- Create
<DOCS_DIR>/02.<N>-design.<component>.mdfor each component - Follow
.claude/skills/project.rules.mdsection "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.mdsection "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.mdfor the docs of a project - Follow
.claude/skills/architecture.rules.mdfor layering and interfaces - Follow
.claude/skills/markdown.rules.mdand.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
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 318k | Updated | Claude CodeCodex | Verified | Install |
| 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: 196k | Updated | Claude CodeCodex | Verified | Install |
| 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: 196k | Updated | Claude CodeCodex | Verified | Install |
| 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: 196k | Updated | Claude CodeCodex | Verified | Install |