gpsaggese/helpers / .claude/skills/architecture.write_design
architecture.write_design
VerifiedWrite the design docs of a project from its PRD, before the code
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 3.3 KB |
SKILL.md
View on GitHub---
description: Write the design docs of a project from its PRD, before the code
model: opus
---
# 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:
```markdown
- 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: 322k | 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: 198k | 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: 198k | 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: 198k | Updated | Claude CodeCodex | Verified | Install |