Requirements to Technical Specs
Product asks arrive as "users should stake and earn yield." Engineering ships account layouts, CPI graphs, and wallet flows. A good spec bridges the gap with testable acceptance criteria before anyone writes Anchor handlers.
Recipe
Quick-reference recipe card - copy-paste ready.
## Feature: Stake SOL for pool shares
### User story
As a holder, I deposit SOL to receive pool tokens representing share.
### On-chain
- Accounts: PoolConfig PDA, UserPosition PDA, vault SOL account
- Instructions: deposit, withdraw
- CPIs: System Program transfer only
### Acceptance
- [ ] LiteSVM: deposit 1 SOL -> mint 1e9 share units
- [ ] Simulation fails if pool paused
- [ ] Client shows confirmed before success toastWhen to reach for this:
- Sprint planning for new protocol feature
- Product proposes token utility change
- Auditor needs feature scope document
- Translating community governance proposal to engineering
Working Example
## Spec: SPL reward claim (v1)
**In scope**
- Claim accrued rewards to user ATA
- Read-only preview via RPC simulate
**Out of scope**
- Auto-compound (v2 RFC)
- Governance vote to change emission rate
**Security**
- Only position owner may claim
- Rewards vault PDA signs transfer via seeds
**UX**
- Wallet signs one tx; show CU estimate
- Error map: Paused, NothingToClaim, InsufficientRentWhat this demonstrates:
- Explicit out-of-scope prevents mid-sprint surprises
- Security bullets become review checklist
- UX error mapping ties program
ErrorCodeto copy
Deep Dive
Spec Layers
| Layer | Audience | Content |
|---|---|---|
| PRD | Product | User outcomes, metrics |
| Tech spec | Eng | Accounts, ix, CPI |
| RFC | Cross-team | Threat model, alternatives |
| Tickets | Implementers | Tasks + tests |
Gotchas
- Vague "support NFTs" - cNFT vs Metaplex vs Core differ 10x in effort. Fix: Name standard and scale.
- No failure cases - Only happy path acceptance. Fix: Attacker and edge cases per instruction.
- Tokenomics hand-wavy - "Community decides" without authority. Fix: Multisig vs governance program spelled out.
- Spec without RPC impact - GPA-heavy feature melts infra. Fix: Read path and indexer noted.
- Changing spec without version bump - Client and program drift. Fix: Spec version in ticket title.
Alternatives
| Alternative | Use When | Don't Use When |
|---|---|---|
| Job stories | DeFi power users | Regulated enterprise needing traceability |
| BDD Gherkin | Client-heavy flows | Low-level account design |
| FigJam only | Brainstorm phase | Fund-holding logic |
FAQs
Who writes the tech spec?
Engineer proposes; product reviews user outcomes; both sign before sprint commit.
How detailed before RFC?
Enough for security review to list accounts and signers.
Community feature requests?
Triage to spec with tokenomics and security appendix.
Spec template?
docs/specs/TEMPLATE.md alongside RFC template.
Estimate from spec?
T-shirt per instruction + CPI class; refine after spike.
Auditor input?
Share spec pre-implementation for scope agreement.
Mobile MWA?
Add wallet flow section to spec for Solana Mobile paths.
Breaking IDL?
Flag in spec; coordinate release train in same doc.
Spec vs ADR?
Spec is feature-scoped and may expire; ADR is architectural record.
Abandoned spec?
Mark withdrawn; link reason to avoid re-debate.
Related
- Running Design Reviews - spec to RFC
- Estimation & Risk - sizing from spec
- Stakeholder Communication - sharing progress
Stack versions: This page was written for Agave 4.1.1, Solana CLI 3.0.10, Anchor 0.32.1, anchor-lang 0.32.1, Rust 1.91.1, @solana/kit 7.0.0, Surfpool 0.12.0, and LiteSVM 0.6.x.