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

FileKindSize
SKILL.mdskill md3.3 KB
---
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`
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: 322kUpdated 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: 198kUpdated 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: 198kUpdated 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: 198kUpdated Claude CodeCodexVerifiedInstall