Requisitos para Especificações Técnicas
Pedidos de produto chegam como "usuários devem fazer stake e ganhar yield". Engenharia entrega layouts de conta, grafos de CPI e fluxos de carteira. Uma boa spec fecha a lacuna com critérios de aceitação testáveis antes de qualquer um escrever handlers Anchor.
Receita
Cartão de receita de referência rápida - pronto para copiar e colar.
## 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 toastQuando usar:
- Sprint planning para nova feature de protocolo
- Produto propõe mudança de utilidade de token
- Auditor precisa de documento de escopo da feature
- Traduzir proposta de governança da comunidade para engenharia
Exemplo Funcional
## 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, InsufficientRentO que isso demonstra:
- Out-of-scope explícito evita surpresas no meio do sprint
- Bullets de segurança viram checklist de review
- Mapeamento de erros UX liga
ErrorCodedo programa ao copy
Aprofundamento
Camadas da Spec
| Camada | Audiência | Conteúdo |
|---|---|---|
| PRD | Produto | Resultados do usuário, métricas |
| Tech spec | Eng | Contas, ix, CPI |
| RFC | Cross-team | Threat model, alternativas |
| Tickets | Implementadores | Tarefas + testes |
Armadilhas
- "support NFTs" vago - cNFT vs Metaplex vs Core diferem 10x em esforço. Correção: Nomeie padrão e escala.
- Sem casos de falha - Apenas happy path na aceitação. Correção: Atacante e edge cases por instrução.
- Tokenomics vago - "Community decides" sem autoridade. Correção: Multisig vs programa de governança explícito.
- Spec sem impacto RPC - Feature pesada em GPA derrete infra. Correção: Caminho de leitura e indexer anotados.
- Mudar spec sem bump de versão - Cliente e programa divergem. Correção: Versão da spec no título do ticket.
Alternativas
| Alternativa | Use quando | Não use quando |
|---|---|---|
| Job stories | Usuários power DeFi | Enterprise regulada precisando rastreabilidade |
| BDD Gherkin | Fluxos pesados em cliente | Design de conta de baixo nível |
| Só FigJam | Fase de brainstorm | Lógica que guarda fundos |
FAQs
Quem escreve a tech spec?
Engenheiro propõe; produto revisa resultados do usuário; ambos assinam antes do commit do sprint.
Quão detalhado antes do RFC?
Suficiente para security review listar contas e signers.
Feature requests da comunidade?
Triagem para spec com apêndice de tokenomics e segurança.
Template de spec?
docs/specs/TEMPLATE.md junto ao template de RFC.
Estimar a partir da spec?
T-shirt por instrução + classe de CPI; refinar após spike.
Input do auditor?
Compartilhe spec pré-implementação para acordo de escopo.
Mobile MWA?
Adicione seção de fluxo de carteira na spec para caminhos Solana Mobile.
IDL breaking?
Sinalize na spec; coordene release train no mesmo doc.
Spec vs ADR?
Spec é escopo de feature e pode expirar; ADR é registro arquitetural.
Spec abandonada?
Marque como withdrawn; linke o motivo para evitar re-debate.
Relacionado
- Running Design Reviews - spec para RFC
- Estimation & Risk - sizing a partir da spec
- Stakeholder Communication - compartilhar progresso
Versões da stack: Esta página foi escrita para 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 e LiteSVM 0.6.x.