113 lines
3.8 KiB
Markdown
113 lines
3.8 KiB
Markdown
# Requirements → Architecture Toolkit for Claude Code
|
|
|
|
Skills and prompts that cover the path from project idea to implementation-ready plan.
|
|
|
|
---
|
|
|
|
## The Tools
|
|
|
|
| Tool | Type | Purpose | Produces |
|
|
|:---------------------------------|:--------------|:--------------------------------------------------|:-----------------------------------------------|
|
|
| `gather-requirements` | Skill | Structured requirements interview | `REQUIREMENTS.md` |
|
|
| `requirements-analyst-prompt.md` | System prompt | Same interview, layered on `/opsx:explore` | `REQUIREMENTS.md` |
|
|
| `architect` | Skill | Collaborative technical design with product owner | `TECHNICAL-SPEC.md` + `IMPLEMENTATION-PLAN.md` |
|
|
|
|
---
|
|
|
|
## Workflow
|
|
|
|
### Without OpenSpec
|
|
|
|
```
|
|
/gather-requirements → REQUIREMENTS.md → /architect → TECHNICAL-SPEC.md
|
|
→ IMPLEMENTATION-PLAN.md
|
|
```
|
|
|
|
### With OpenSpec
|
|
|
|
```
|
|
claude --append-system-prompt-file requirements-analyst-prompt.md
|
|
└─► /opsx:explore (structured requirements interview)
|
|
└─► REQUIREMENTS.md captured
|
|
└─► /architect (in same or new session)
|
|
└─► TECHNICAL-SPEC.md + IMPLEMENTATION-PLAN.md
|
|
└─► /opsx:new my-feature
|
|
└─► /opsx:ff (informed by all three documents)
|
|
```
|
|
|
|
---
|
|
|
|
## Install
|
|
|
|
### Skills
|
|
|
|
```bash
|
|
# Project-level
|
|
mkdir -p .claude/skills
|
|
cp -r gather-requirements .claude/skills/
|
|
cp -r architect .claude/skills/
|
|
|
|
# OR User-level (all projects)
|
|
cp -r gather-requirements ~/.claude/skills/
|
|
cp -r architect ~/.claude/skills/
|
|
```
|
|
|
|
### System prompt (for OpenSpec workflow)
|
|
|
|
Keep `requirements-analyst-prompt.md` wherever you like. Reference it at launch:
|
|
|
|
```bash
|
|
claude --append-system-prompt-file /path/to/requirements-analyst-prompt.md
|
|
```
|
|
|
|
---
|
|
|
|
## Usage
|
|
|
|
### /gather-requirements
|
|
|
|
```
|
|
$ claude
|
|
> /gather-requirements
|
|
```
|
|
|
|
Claude interviews you in 6 phases (vision, users, functional, non-functional, constraints, priorities) and writes `REQUIREMENTS.md` with numbered requirement IDs.
|
|
|
|
### /architect
|
|
|
|
```
|
|
$ claude
|
|
> /architect
|
|
```
|
|
|
|
Claude reads `REQUIREMENTS.md` and works through the design collaboratively with you as product owner. You'll discuss and decide together on:
|
|
|
|
- Architecture approach (monolith, services, serverless, etc.)
|
|
- Technology stack
|
|
- Data architecture
|
|
- API and integration design
|
|
- Testing strategy (your call — Claude presents options)
|
|
- Infrastructure and deployment
|
|
- Security
|
|
- Delivery approach and phasing
|
|
|
|
After the sessions, Claude writes `TECHNICAL-SPEC.md` and `IMPLEMENTATION-PLAN.md`. All three documents share a common vocabulary of requirement IDs, component names, and task IDs for full traceability.
|
|
|
|
### OpenSpec prompt
|
|
|
|
```bash
|
|
claude --append-system-prompt-file requirements-analyst-prompt.md
|
|
> /opsx:explore
|
|
```
|
|
|
|
Same structured interview, woven into OpenSpec's explore mode. When insights crystallize, Claude offers to capture `REQUIREMENTS.md` before you transition to `/opsx:new`.
|
|
|
|
---
|
|
|
|
## Tips
|
|
|
|
- **Sequence matters.** Requirements first, architecture second. The architect skill expects `REQUIREMENTS.md` to exist.
|
|
- **"I don't know" is fine.** In requirements, unknowns become open questions. In architecture, they become assumptions — clearly marked so the team can revisit.
|
|
- **Iterate.** Both skills update documents in place. Re-run `/architect` after refining requirements.
|
|
- **IDs carry forward.** FR-001 in requirements maps to components in the spec and tasks in the plan. This traceability is the point — it lets the team verify nothing was lost.
|