architecture-decision-records

Name: architecture-decision-records
Author: SamarthaKV29

64stars12forks

How to install architecture-decision-records?

samarthakv29/antigravity-god-mode/architecture-decision-records

$npx -y skills add SamarthaKV29/antigravity-god-mode --skill architecture-decision-records

Installs into the current project.

Summary

Write and maintain Architecture Decision Records (ADRs) following best practices for technical decision documentation. Use when documenting significant technical decisions, reviewing past architectural choices, or establishing decision processes.

Files · 1

View on GitHub

SKILL.md

1	# Architecture Decision Records
2
3	Comprehensive patterns for creating, maintaining, and managing Architecture Decision Records (ADRs) that capture the context and rationale behind significant technical decisions.
4
5	## Use this skill when
6
7	- Making significant architectural decisions
8	- Documenting technology choices
9	- Recording design trade-offs
10	- Onboarding new team members
11	- Reviewing historical decisions
12	- Establishing decision-making processes
13
14	## Do not use this skill when
15
16	- You only need to document small implementation details
17	- The change is a minor patch or routine maintenance
18	- There is no architectural decision to capture
19
20	## Instructions
21
22	1. Capture the decision context, constraints, and drivers.
23	2. Document considered options with tradeoffs.
24	3. Record the decision, rationale, and consequences.
25	4. Link related ADRs and update status over time.
26
27	## Core Concepts
28
29	### 1. What is an ADR?
30
31	An Architecture Decision Record captures:
32	- Context: Why we needed to make a decision
33	- Decision: What we decided
34	- Consequences: What happens as a result
35
36	### 2. When to Write an ADR
37
38	\| Write ADR \| Skip ADR \|
39	\|-----------\|----------\|
40	\| New framework adoption \| Minor version upgrades \|
41	\| Database technology choice \| Bug fixes \|
42	\| API design patterns \| Implementation details \|
43	\| Security architecture \| Routine maintenance \|
44	\| Integration patterns \| Configuration changes \|
45
46	### 3. ADR Lifecycle
47
48	```
49	Proposed → Accepted → Deprecated → Superseded
50	↓
51	Rejected
52	```
53
54	## Templates
55
56	### Template 1: Standard ADR (MADR Format)
57
58	```markdown
59	# ADR-0001: Use PostgreSQL as Primary Database
60
61	## Status
62
63	Accepted
64
65	## Context
66
67	We need to select a primary database for our new e-commerce platform. The system
68	will handle:
69	- ~10,000 concurrent users
70	- Complex product catalog with hierarchical categories
71	- Transaction processing for orders and payments
72	- Full-text search for products
73	- Geospatial queries for store locator
74
75	The team has experience with MySQL, PostgreSQL, and MongoDB. We need ACID
76	compliance for financial transactions.
77
78	## Decision Drivers
79
80	* Must have ACID compliance for payment processing
81	* Must support complex queries for reporting
82	* Should support full-text search to reduce infrastructure complexity
83	* Should have good JSON support for flexible product attributes
84	* Team familiarity reduces onboarding time
85
86	## Considered Options
87
88	### Option 1: PostgreSQL
89	- Pros: ACID compliant, excellent JSON support (JSONB), built-in full-text
90	search, PostGIS for geospatial, team has experience
91	- Cons: Slightly more complex replication setup than MySQL
92
93	### Option 2: MySQL
94	- Pros: Very familiar to team, simple replication, large community
95	- Cons: Weaker JSON support, no built-in full-text search (need
96	Elasticsearch), no geospatial without extensions
97
98	### Option 3: MongoDB
99	- Pros: Flexible schema, native JSON, horizontal scaling
100	- Cons: No ACID for multi-document transactions (at decision time),
101	team has limited experience, requires schema design discipline
102
103	## Decision
104
105	We will use PostgreSQL 15 as our primary database.
106
107	## Rationale
108
109	PostgreSQL provides the best balance of:
110	1. ACID compliance essential for e-commerce transactions
111	2. Built-in capabilities (full-text search, JSONB, PostGIS) reduce
112	infrastructure complexity
113	3. Team familiarity with SQL databases reduces learning curve
114	4. Mature ecosystem with excellent tooling and community support
115
116	The slight complexity in replication is outweighed by the reduction in
117	additional services (no separate Elasticsearch needed).
118
119	## Consequences
120
121	### Positive
122	- Single database handles transactions, search, and geospatial queries
123	- Reduced operational complexity (fewer services to manage)
124	- Strong consistency guarantees for financial data
125	- Team can leverage existing SQL expertise
126
127	### Negative
128	- Need to learn PostgreSQL-specific features (JSONB, full-text search syntax)
129	- Vertical scaling limits may require read replicas sooner
130	- Some team members need PostgreSQL-specific training
131
132	### Risks
133	- Full-text search may not scale as well as dedicated search engines
134	- Mitigation: Design for potential Elasticsearch addition if needed
135
136	## Implementation Notes
137
138	- Use JSONB for flexible product attributes
139	- Implement connection pooling with PgBouncer
140	- Set up streaming replication for read replicas
141	- Use pg_trgm extension for fuzzy search
142
143	## Related Decisions
144
145	- ADR-0002: Caching Strategy (Redis) - complements database choice
146	- ADR-0005: Search Architecture - may supersede if Elasticsearch needed
147
148	## References
149
150	- [PostgreSQL JSON Documentation](https://www.postgresql.org/docs/current/datatype-json.h

People who liked this also viewed

6 picks

Type

architecture-decision-records

64stars12forks

View on GitHub

How to install architecture-decision-records?

samarthakv29/antigravity-god-mode/architecture-decision-records

$npx -y skills add SamarthaKV29/antigravity-god-mode --skill architecture-decision-records

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Architecture Decision Records
2
3	Comprehensive patterns for creating, maintaining, and managing Architecture Decision Records (ADRs) that capture the context and rationale behind significant technical decisions.
4
5	## Use this skill when
6
7	- Making significant architectural decisions
8	- Documenting technology choices
9	- Recording design trade-offs
10	- Onboarding new team members
11	- Reviewing historical decisions
12	- Establishing decision-making processes
13
14	## Do not use this skill when
15
16	- You only need to document small implementation details
17	- The change is a minor patch or routine maintenance
18	- There is no architectural decision to capture
19
20	## Instructions
21
22	1. Capture the decision context, constraints, and drivers.
23	2. Document considered options with tradeoffs.
24	3. Record the decision, rationale, and consequences.
25	4. Link related ADRs and update status over time.
26
27	## Core Concepts
28
29	### 1. What is an ADR?
30
31	An Architecture Decision Record captures:
32	- Context: Why we needed to make a decision
33	- Decision: What we decided
34	- Consequences: What happens as a result
35
36	### 2. When to Write an ADR
37
38	\| Write ADR \| Skip ADR \|
39	\|-----------\|----------\|
40	\| New framework adoption \| Minor version upgrades \|
41	\| Database technology choice \| Bug fixes \|
42	\| API design patterns \| Implementation details \|
43	\| Security architecture \| Routine maintenance \|
44	\| Integration patterns \| Configuration changes \|
45
46	### 3. ADR Lifecycle
47
48	```
49	Proposed → Accepted → Deprecated → Superseded
50	↓
51	Rejected
52	```
53
54	## Templates
55
56	### Template 1: Standard ADR (MADR Format)
57
58	```markdown
59	# ADR-0001: Use PostgreSQL as Primary Database
60
61	## Status
62
63	Accepted
64
65	## Context
66
67	We need to select a primary database for our new e-commerce platform. The system
68	will handle:
69	- ~10,000 concurrent users
70	- Complex product catalog with hierarchical categories
71	- Transaction processing for orders and payments
72	- Full-text search for products
73	- Geospatial queries for store locator
74
75	The team has experience with MySQL, PostgreSQL, and MongoDB. We need ACID
76	compliance for financial transactions.
77
78	## Decision Drivers
79
80	* Must have ACID compliance for payment processing
81	* Must support complex queries for reporting
82	* Should support full-text search to reduce infrastructure complexity
83	* Should have good JSON support for flexible product attributes
84	* Team familiarity reduces onboarding time
85
86	## Considered Options
87
88	### Option 1: PostgreSQL
89	- Pros: ACID compliant, excellent JSON support (JSONB), built-in full-text
90	search, PostGIS for geospatial, team has experience
91	- Cons: Slightly more complex replication setup than MySQL
92
93	### Option 2: MySQL
94	- Pros: Very familiar to team, simple replication, large community
95	- Cons: Weaker JSON support, no built-in full-text search (need
96	Elasticsearch), no geospatial without extensions
97
98	### Option 3: MongoDB
99	- Pros: Flexible schema, native JSON, horizontal scaling
100	- Cons: No ACID for multi-document transactions (at decision time),
101	team has limited experience, requires schema design discipline
102
103	## Decision
104
105	We will use PostgreSQL 15 as our primary database.
106
107	## Rationale
108
109	PostgreSQL provides the best balance of:
110	1. ACID compliance essential for e-commerce transactions
111	2. Built-in capabilities (full-text search, JSONB, PostGIS) reduce
112	infrastructure complexity
113	3. Team familiarity with SQL databases reduces learning curve
114	4. Mature ecosystem with excellent tooling and community support
115
116	The slight complexity in replication is outweighed by the reduction in
117	additional services (no separate Elasticsearch needed).
118
119	## Consequences
120
121	### Positive
122	- Single database handles transactions, search, and geospatial queries
123	- Reduced operational complexity (fewer services to manage)
124	- Strong consistency guarantees for financial data
125	- Team can leverage existing SQL expertise
126
127	### Negative
128	- Need to learn PostgreSQL-specific features (JSONB, full-text search syntax)
129	- Vertical scaling limits may require read replicas sooner
130	- Some team members need PostgreSQL-specific training
131
132	### Risks
133	- Full-text search may not scale as well as dedicated search engines
134	- Mitigation: Design for potential Elasticsearch addition if needed
135
136	## Implementation Notes
137
138	- Use JSONB for flexible product attributes
139	- Implement connection pooling with PgBouncer
140	- Set up streaming replication for read replicas
141	- Use pg_trgm extension for fuzzy search
142
143	## Related Decisions
144
145	- ADR-0002: Caching Strategy (Redis) - complements database choice
146	- ADR-0005: Search Architecture - may supersede if Elasticsearch needed
147
148	## References
149
150	- [PostgreSQL JSON Documentation](https://www.postgresql.org/docs/current/datatype-json.h

People who liked this also viewed

6 picks

Type