tranhieutt/architecture-decision-records
.claude/skills/architecture-decision-records/SKILL.md
Manages the ADR (Architecture Decision Record) registry in docs/decisions/. Use when listing, searching, or creating ADRs, or when the user mentions architectural decisions, ADR, or design records.
$ install --global
skillsauthnpx skillsauth add tranhieutt/software_development_department architecture-decision-recordsInstall this skill globally with one command. Works with Claude Code, Cursor, and Windsurf.
Security Scan Results
3 of 9 scanners reported clean
Some scanners were skipped, did not run, or reported a non-clean status. Review each row below.
3
Scanners Passed
9
Scanners in report
Clean
TrivyContainer and dependency vulnerability scanner
95%
Clean
SemgrepStatic code analysis for vulnerabilities
95%
Clean
mcp-scan (Snyk)Model Context Protocol security validation
95%
Skipped
Snyk (dep)Open source security scanning
50%
Skipped
Socket.devSupply chain security analysis
50%
Skipped
VirusTotalMulti-engine malware detection
50%
Skipped
CrowdStrikeAdvanced threat intelligence
50%
Skipped
OSV-ScannerOpen Source Vulnerability database check
50%
Skipped
OWASP Dep-Check
50%
Last scanned: Apr 15, 2026, 11:47 PM11.8s1 file scanned
SKILL.md
- name:
- architecture-decision-records
- description:
- Manages the ADR (Architecture Decision Record) registry in docs/decisions/. Use when listing, searching, or creating ADRs, or when the user mentions architectural decisions, ADR, or design records.
- context:
- fork
- agent:
- technical-director
- allowed-tools:
- Read, Glob, Grep, Write, Bash
- argument-hint:
- [decision topic or question]
- user-invocable:
- true
- effort:
- 4
- when_to_use:
- When needing to create a formal ADR document with full context and alternatives
Architecture Decision Records
When to write an ADR vs skip
| Write ADR | Skip ADR | |---|---| | New framework/database adoption | Minor version upgrades | | API design patterns | Bug fixes | | Security architecture | Implementation details | | Integration patterns | Routine maintenance |
ADR lifecycle
Proposed → Accepted → Deprecated → Superseded
↓
Rejected
Template (MADR format — use this)
# ADR-NNNN: [Title]
## Status
Accepted | Proposed | Deprecated | Superseded by ADR-XXXX
## Context
[Problem statement, current situation, constraints, scale]
## Decision Drivers
- [Must/Should/Could requirement]
## Considered Options
### Option 1: [Name] — [one-line summary]
Pros: ... | Cons: ...
### Option 2: [Name]
Pros: ... | Cons: ...
## Decision
We will use **[Option N]** because [key rationale].
## Consequences
**Positive:** ...
**Negative:** ...
**Risks:** ... Mitigation: ...
## Related ADRs
- ADR-XXXX: [relationship]
Quick examples
Lightweight ADR (for clear-cut decisions):
# ADR-0012: Adopt TypeScript for Frontend
**Status**: Accepted | **Date**: 2024-01-15 | **Deciders**: @alice, @bob
## Context
50+ React components with prop-type-mismatch bugs. PropTypes are runtime-only.
## Decision
TypeScript for all new frontend code. Migrate incrementally with `allowJs: true`.
## Consequences
Good: Compile-time errors, better IDE support.
Bad: Learning curve, initial slowdown.
Y-Statement (for concise formal record):
In the context of **building a microservices architecture**,
facing **need for centralized auth and rate limiting**,
we decided for **Kong Gateway**
and against **AWS API Gateway and custom Nginx**,
to achieve **vendor independence and plugin extensibility**,
accepting **we manage Kong infrastructure ourselves**.
File structure
docs/adr/
├── README.md # Index table
├── template.md
├── 0001-use-postgresql.md
└── 0003-mongodb-deprecated.md # [SUPERSEDED by 0020]
Index table (maintain in README.md)
| ADR | Title | Status | Date | |---|---|---|---| | 0001 | Use PostgreSQL | Accepted | 2024-01-10 | | 0003 | MongoDB for profiles | Deprecated | 2023-06-15 |
Key rules
- Never modify accepted ADRs — write a new one to supersede
- Write early — before implementation starts, not after
- Max 1-2 pages — if longer, decision scope is too broad
- State real cons — an ADR without honest tradeoffs has no value
- Update status — mark deprecated when superseded; link the new ADR
Automation
# With adr-tools
adr init docs/adr
adr new "Use PostgreSQL as Primary Database"
adr new -s 3 "Deprecate MongoDB" # -s supersedes ADR 3
adr generate toc > docs/adr/README.md
Related Skills
tranhieutt/visual-engineer
testing
VerifiedTrustedCommunity
Generates high-fidelity architecture diagrams, sequence flows, and component maps for SDD projects. Use when finalizing a design phase, documenting system architecture, or visualizing agentic workflows. Default style: Style 6 (Claude Official).
60SKILL.mdUpdated Apr 15, 2026
tranhieutt/vector-database-engineer
data-ai
VerifiedTrustedCommunity
Provides vector database and semantic search patterns for Pinecone, Weaviate, Qdrant, Milvus, and pgvector in RAG and recommendation systems. Use when implementing vector search or when the user mentions vector database, semantic search, embeddings, or similarity search.
60SKILL.mdUpdated Apr 15, 2026
tranhieutt/update-codemap
development
VerifiedTrustedCommunity
Updates docs/technical/CODEMAP.md by scanning the current codebase structure. Run after a significant feature merge, refactor, or when CODEMAP feels stale.
60SKILL.mdUpdated Apr 15, 2026
tranhieutt/unfreeze
development
VerifiedTrustedCommunity
Unlocks the codebase after a release freeze or incident freeze period to resume normal development. Use when a freeze period ends or when the user mentions unfreezing or lifting the code freeze.
60SKILL.mdUpdated Apr 15, 2026