diegosouzapw create-adrs
Skill Type: Actuator (Design Documentation) Purpose: Document architecture decisions acknowledging ecosystem E(t) Prerequisites: Strategic technical decision needed
Agent Instructions
You are creating Architecture Decision Records (ADRs) that acknowledge ecosystem E(t) constraints.
Critical: ADRs document GIVEN constraints (E(t)), not just CHOSEN solutions.
Format: "Given E(t), we chose X" (not "we chose X")
ADR Structure
Template
# ADR-{ID}: {Decision Title}
**Date**: {YYYY-MM-DD}
**Status**: Accepted | Rejected | Superseded | Deprecated
**Deciders**: {Who made this decision}
---
## Context
**Requirements**:
- <REQ-ID>: User authentication
- REQ-NFR-SEC-001: Secure password storage
**Problem**:
We need to choose a password hashing algorithm that is secure
against brute force attacks while maintaining acceptable performance.
**Ecosystem E(t) Constraints**:
- Team Experience: Team familiar with bcrypt
- Infrastructure: Running on AWS (bcrypt supported)
- Compliance: PCI-DSS recommends strong hashing
- Performance: Login response must be < 500ms (REQ-NFR-PERF-001)
- Libraries Available: bcrypt, argon2, scrypt available
---
## Decision
**Selected**: bcrypt with cost factor 12
**Rejected Alternatives**:
- SHA256: ❌ Too fast (vulnerable to brute force)
- MD5: ❌ Cryptographically broken
- Argon2: ⚠️ Better security but team unfamiliar, migration risk
- scrypt: ⚠️ Good security but less widely supported
**Rationale**:
1. bcrypt is industry standard (acknowledged E(t))
2. Team has experience with bcrypt (acknowledge E(t) - team capabilities)
3. Cost factor 12 balances security and performance
4. Meets PCI-DSS requirements (acknowledge E(t) - compliance)
5. Login tests show 200ms average (well within 500ms SLA)
---
## Ecosystem Constraints Acknowledged
**Team** (E(t)):
- Team knows: bcrypt, SHA256
- Team doesn't know: Argon2 implementation
- Risk: Learning curve with Argon2
**Infrastructure** (E(t)):
- Platform: AWS Lambda + RDS PostgreSQL
- bcrypt: Native support, no additional dependencies
- Argon2: Would need custom layer
**Compliance** (E(t)):
- PCI-DSS: Requires strong, salted hashing
- bcrypt: Explicitly mentioned in PCI guidelines
- Audit: External auditors familiar with bcrypt
**Performance** (E(t)):
- Requirement: Login < 500ms (REQ-NFR-PERF-001)
- bcrypt (cost 12): ~200ms (acceptable)
- Argon2: ~250ms (acceptable but no experience)
**Timeline** (E(t)):
- Sprint: 2 weeks
- bcrypt: No learning curve (immediate)
- Argon2: 2-3 days research + testing
---
## Constraints Imposed Downstream
**Code Stage** (constraints for implementation):
- MUST use bcrypt library (not custom hashing)
- MUST use cost factor 12 (not lower)
- MUST salt passwords (bcrypt does this automatically)
**Runtime Stage** (constraints for deployment):
- Infrastructure: bcrypt library must be available
- Performance monitoring: Track hash time (should be ~200ms)
**Testing Stage**:
- Test hash time (ensure < 500ms)
- Test bcrypt version (security updates)
---
## Consequences
**Positive**:
- ✅ Team productive immediately (no learning curve)
- ✅ Proven security (industry standard)
- ✅ PCI-DSS compliant (audit-friendly)
- ✅ Performance acceptable (< 500ms)
**Negative**:
- ⚠️ Not latest algorithm (Argon2 is newer)
- ⚠️ Vendor lock-in to bcrypt (migration costly)
**Neutral**:
- Cost factor 12 is balance (could be 10 for faster, 14 for stronger)
---
## Related Decisions
- ADR-001: Database selection (PostgreSQL)
- ADR-003: Session management (JWT)
**Supersedes**: None
**Superseded By**: None
---
## References
- PCI-DSS Password Requirements: https://www.pcisecuritystandards.org/
- bcrypt Documentation: https://en.wikipedia.org/wiki/Bcrypt
- OWASP Password Storage: https://cheatsheetseries.owasp.org/cheatsheets/Password_Storage_Cheat_Sheet.html
ADR Numbering
Sequential: ADR-001, ADR-002, ADR-003, ...
Categories:
- Infrastructure: Cloud provider, hosting, databases
- Security: Authentication, encryption, authorization
- Architecture: Patterns, frameworks, languages
- Integration: APIs, external services
- Data: Storage, schemas, migration
When to Create ADRs
Create ADR for:
- ✅ Cloud provider choice (AWS vs GCP vs Azure)
- ✅ Language/framework choice (Python vs Node vs Java)
- ✅ Database choice (PostgreSQL vs MySQL vs MongoDB)
- ✅ Authentication approach (JWT vs sessions vs OAuth)
- ✅ API style (REST vs GraphQL vs gRPC)
- ✅ Architectural pattern (monolith vs microservices)
Don't create ADR for:
- ❌ Implementation details (already covered by code)
- ❌ Tactical decisions (variable names, file structure)
- ❌ Obvious choices (using standard library)
Output Format
[CREATE ADR - bcrypt Password Hashing]
Decision: Use bcrypt for password hashing
Context:
Requirements: <REQ-ID>, REQ-NFR-SEC-001
Problem: Need secure password hashing
Ecosystem E(t): Team knows bcrypt, PCI-DSS compliant, AWS supported
Decision:
Selected: bcrypt (cost factor 12)
Rejected: SHA256 (too fast), Argon2 (team unfamiliar)
Ecosystem Constraints Acknowledged:
- Team capabilities: knows bcrypt ✓
- Compliance: PCI-DSS requires strong hashing ✓
- Performance: Must be < 500ms ✓
- Infrastructure: AWS supports bcrypt ✓
Constraints Imposed:
- Code must use bcrypt library
- Code must use cost factor 12
- Runtime must have bcrypt available
Created: docs/adrs/ADR-002-password-hashing.md
✅ ADR Created!
Architecture decision documented
Ecosystem E(t) acknowledged
Downstream constraints clear
Notes
Why ADRs?
- Document "why": Explains reasoning behind decisions
- Acknowledge E(t): Shows we understand ecosystem constraints
- Prevent re-litigation: Decision made, recorded, done
- Onboarding: New team members understand past decisions
ADRs vs Constraints (C-*):
- C-*: Given constraints we MUST work within
- ADR: Chosen solutions GIVEN those constraints
Example:
C-001: PCI-DSS requires strong password hashing (GIVEN)
ADR-002: We chose bcrypt (GIVEN C-001 and team skills)
Homeostasis Goal:
desired_state:
all_strategic_decisions_documented: true
ecosystem_constraints_acknowledged: true
rationale_clear: true
"Excellence or nothing" 🔥