Add architecture beliefs to manifesto and enhance software-architecture skill
- Add Architecture Beliefs section to manifesto with outcome-focused beliefs: auditability, business language in code, independent evolution, explicit over implicit - Create software-architecture.md as human-readable documentation - Enhance software-architecture skill with beliefs→patterns mapping (DDD, Event Sourcing, event-driven communication) and auto-trigger description - Update work-issue command to reference skill and check project architecture - Update issue-worker agent with software-architecture skill - Add Architecture section template to vision-management skill The skill is now auto-triggered when implementing, reviewing, or planning architectural work. Project-level architecture choices go in vision.md. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
@@ -1,12 +1,149 @@
|
||||
---
|
||||
name: software-architecture
|
||||
description: Software architecture best practices, patterns, and review guidance. Foundation for architecture-related agents and commands including repo audits, issue refinement, and PR reviews.
|
||||
description: >
|
||||
Architectural patterns for building systems: DDD, Event Sourcing, event-driven communication.
|
||||
Use when implementing features, reviewing code, planning issues, refining architecture,
|
||||
or making design decisions. Ensures alignment with organizational beliefs about
|
||||
auditability, domain modeling, and independent evolution.
|
||||
user-invocable: false
|
||||
---
|
||||
|
||||
# Software Architecture
|
||||
|
||||
Best practices, patterns, and review guidance for software architecture. This skill serves as the knowledge base for architecture-related agents and commands.
|
||||
Architectural patterns and best practices. This skill is auto-triggered when implementing, reviewing, or planning work that involves architectural decisions.
|
||||
|
||||
## Architecture Beliefs
|
||||
|
||||
These outcome-focused beliefs (from our organization manifesto) guide architectural decisions:
|
||||
|
||||
| Belief | Why It Matters |
|
||||
|--------|----------------|
|
||||
| **Auditability by default** | Systems should remember what happened, not just current state |
|
||||
| **Business language in code** | Domain experts' words should appear in the codebase |
|
||||
| **Independent evolution** | Parts should change without breaking other parts |
|
||||
| **Explicit over implicit** | Intent and side effects should be visible and traceable |
|
||||
|
||||
## Beliefs → Patterns
|
||||
|
||||
| Belief | Primary Pattern | Supporting Patterns |
|
||||
|--------|-----------------|---------------------|
|
||||
| Auditability by default | Event Sourcing | Immutable events, temporal queries |
|
||||
| Business language in code | Domain-Driven Design | Ubiquitous language, aggregates, bounded contexts |
|
||||
| Independent evolution | Event-driven communication | Bounded contexts, published language |
|
||||
| Explicit over implicit | Commands and Events | Domain events, clear intent |
|
||||
|
||||
## Event Sourcing
|
||||
|
||||
**Achieves:** Auditability by default
|
||||
|
||||
Instead of storing current state, store the sequence of events that led to it.
|
||||
|
||||
**Core concepts:**
|
||||
- **Events** are immutable facts about what happened, named in past tense: `OrderPlaced`, `PaymentReceived`
|
||||
- **State** is derived by replaying events, not stored directly
|
||||
- **Event store** is append-only - history is never modified
|
||||
|
||||
**Why this matters:**
|
||||
- Complete audit trail for free
|
||||
- Debug by replaying history
|
||||
- Answer "what was the state at time X?"
|
||||
- Recover from bugs by fixing logic and replaying
|
||||
|
||||
**Trade-offs:**
|
||||
- More complex than CRUD for simple cases
|
||||
- Requires thinking in events, not state
|
||||
- Eventually consistent read models
|
||||
|
||||
## Domain-Driven Design
|
||||
|
||||
**Achieves:** Business language in code
|
||||
|
||||
The domain model reflects how the business thinks and talks.
|
||||
|
||||
**Core concepts:**
|
||||
- **Ubiquitous language** - same terms in code, conversations, and documentation
|
||||
- **Bounded contexts** - explicit boundaries where terms have consistent meaning
|
||||
- **Aggregates** - clusters of objects that change together, with one root entity
|
||||
- **Domain events** - capture what happened in business terms
|
||||
|
||||
**Why this matters:**
|
||||
- Domain experts can read and validate the model
|
||||
- New team members learn the domain through code
|
||||
- Changes in business rules map clearly to code changes
|
||||
|
||||
**Trade-offs:**
|
||||
- Upfront investment in understanding the domain
|
||||
- Boundaries may need to shift as understanding grows
|
||||
- Overkill for pure technical/infrastructure code
|
||||
|
||||
## Event-Driven Communication
|
||||
|
||||
**Achieves:** Independent evolution
|
||||
|
||||
Services communicate by publishing events, not calling each other directly.
|
||||
|
||||
**Core concepts:**
|
||||
- **Publish events** when something important happens
|
||||
- **Subscribe to events** you care about
|
||||
- **No direct dependencies** between publisher and subscriber
|
||||
- **Eventual consistency** - accept that not everything updates instantly
|
||||
|
||||
**Why this matters:**
|
||||
- Add new services without changing existing ones
|
||||
- Services can be deployed independently
|
||||
- Natural resilience - if a subscriber is down, events queue
|
||||
|
||||
**Trade-offs:**
|
||||
- Harder to trace request flow
|
||||
- Eventual consistency requires different thinking
|
||||
- Need infrastructure for reliable event delivery
|
||||
|
||||
## Commands and Events
|
||||
|
||||
**Achieves:** Explicit over implicit
|
||||
|
||||
Distinguish between requests (commands) and facts (events).
|
||||
|
||||
**Core concepts:**
|
||||
- **Commands** express intent: `PlaceOrder`, `CancelSubscription`
|
||||
- Commands can be rejected (validation, business rules)
|
||||
- **Events** express facts: `OrderPlaced`, `SubscriptionCancelled`
|
||||
- Events are immutable - what happened, happened
|
||||
|
||||
**Why this matters:**
|
||||
- Clear separation of "trying to do X" vs "X happened"
|
||||
- Commands validate, events just record
|
||||
- Enables replay - reprocess events with new logic
|
||||
|
||||
## When to Diverge
|
||||
|
||||
These patterns are defaults, not mandates. Diverge intentionally when:
|
||||
|
||||
- **Simplicity wins** - a simple CRUD endpoint doesn't need event sourcing
|
||||
- **Performance requires it** - sometimes synchronous calls are necessary
|
||||
- **Team context** - patterns the team doesn't understand cause more harm than good
|
||||
- **Prototyping** - validate ideas before investing in full architecture
|
||||
|
||||
When diverging, document the decision in the project's `vision.md` Architecture section.
|
||||
|
||||
## Project-Level Architecture
|
||||
|
||||
Each project documents architectural choices in `vision.md`:
|
||||
|
||||
```markdown
|
||||
## Architecture
|
||||
|
||||
This project follows organization architecture patterns.
|
||||
|
||||
### Alignment
|
||||
- Event sourcing for [which aggregates/domains]
|
||||
- Bounded contexts: [list contexts and their responsibilities]
|
||||
- Event-driven communication between [which services]
|
||||
|
||||
### Intentional Divergences
|
||||
| Area | Standard Pattern | What We Do Instead | Why |
|
||||
|------|------------------|-------------------|-----|
|
||||
```
|
||||
|
||||
## Go-Specific Best Practices
|
||||
|
||||
|
||||
@@ -123,6 +123,17 @@ These extend the organization's guiding principles:
|
||||
These extend the organization's non-goals:
|
||||
|
||||
- **[Non-goal].** [Explanation]
|
||||
|
||||
## Architecture
|
||||
|
||||
This project follows organization architecture patterns (see software-architecture skill).
|
||||
|
||||
### Alignment
|
||||
- [Which patterns we use and where]
|
||||
|
||||
### Intentional Divergences
|
||||
| Area | Standard Pattern | What We Do Instead | Why |
|
||||
|------|------------------|-------------------|-----|
|
||||
```
|
||||
|
||||
### When to Update Vision
|
||||
|
||||
Reference in New Issue
Block a user