im-shashanks/claude-plugins / shaktra/skills/shaktra-tdd
shaktra-tdd
VerifiedTDD knowledge base — testing practices, coding practices, and implementation patterns. Loaded by SDM workflow agents (sw-engineer, test-agent, developer) for behavioral testing guidance and production-grade coding standards.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 4.9 KB |
| api-design-practices.md | markdown | 6.4 KB |
| architecture-governance-practices.md | markdown | 5.5 KB |
| coding-practices.md | markdown | 9.1 KB |
| concurrency-practices.md | markdown | 5.9 KB |
| data-layer-practices.md | markdown | 6.2 KB |
| performance-practices.md | markdown | 7.1 KB |
| refactoring-smells.md | markdown | 7.8 KB |
| refactoring-transforms.md | markdown | 9.8 KB |
| resilience-practices.md | markdown | 5.8 KB |
| schema-design-practices.md | markdown | 5.8 KB |
| security-practices.md | markdown | 8.0 KB |
| service-boundary-practices.md | markdown | 5.7 KB |
| testing-practices.md | markdown | 6.2 KB |
| threat-modeling-practices.md | markdown | 6.5 KB |
service-boundary-practices.md
View on GitHub# Service Boundary Practices
Design-first service and module boundary practices. Loaded by the architect agent during design doc creation and by tpm-quality during design review. Ensures clean ownership, explicit communication contracts, and failure isolation before implementation begins.
---
## 1. Bounded Context Identification
### Entity Ownership
Every domain entity belongs to exactly one bounded context:
- The owning context is the **single source of truth** for that entity's state
- Other contexts hold read-only projections, not copies
- When in doubt, ask: "Who creates, updates, and deletes this entity?" — that's the owner
### Context Mapping
Document relationships between bounded contexts:
| Relationship | Pattern | Example |
|-------------|---------|---------|
| **Shared Kernel** | Shared code/schema, both teams must agree on changes | Common domain types |
| **Customer-Supplier** | Upstream supplies, downstream consumes; upstream accommodates | Payment service → Order service |
| **Conformist** | Downstream conforms to upstream's model without influence | Third-party API integration |
| **Anti-Corruption Layer** | Downstream translates upstream's model to protect its own | Legacy system integration |
| **Published Language** | Shared schema/protocol (OpenAPI, Protobuf, Avro) | Public API contracts |
### Ubiquitous Language
- Each bounded context has its own vocabulary
- The same real-world concept may have different names in different contexts (User vs Customer vs Account)
- Document the mapping between contexts when the same concept appears in multiple contexts
---
## 2. Data Ownership
### Single Writer Principle
- Each piece of data has **exactly one service** that writes it
- Other services read via API, event, or read-only database view — never direct write access
- Violations indicate a missing service boundary or a shared database anti-pattern
### Read-Only Access Patterns
| Pattern | Use When | Trade-offs |
|---------|---------|-----------|
| API call | Strong consistency needed, low volume | Latency, coupling, availability dependency |
| Event subscription | Eventual consistency acceptable | Complexity, ordering, replay needed |
| Read replica / view | High read volume, low change frequency | Stale data, operational overhead |
| Cache with invalidation | Frequently read, rarely changed | Stale risk, invalidation complexity |
### Anti-Corruption Layer
When integrating with external or legacy systems:
- Never expose external models directly in your domain
- Translate at the boundary: external DTO → internal domain model
- Isolate integration code in a dedicated adapter module
- Changes to external systems affect only the adapter, not domain logic
---
## 3. Communication Patterns
### Sync vs Async Decision Matrix
| Factor | Prefer Sync (HTTP/gRPC) | Prefer Async (Events/Queues) |
|--------|------------------------|------|
| Response needed immediately | Yes | No |
| Consumer must know result | Yes | No |
| Temporal coupling acceptable | Yes | No |
| Multiple consumers | No | Yes |
| Spike tolerance needed | No | Yes |
| Order matters | N/A | Depends on guarantee |
### Sync Dependency Requirements
Every synchronous dependency must specify:
- **Timeout:** Connect timeout + read timeout (never unbounded)
- **Retry policy:** Max retries, backoff strategy, idempotency requirement
- **Circuit breaker:** Failure threshold, open duration, half-open behavior
- **Fallback:** What happens when the dependency is unavailable
### Async Delivery Guarantees
| Guarantee | Meaning | Implementation |
|-----------|---------|---------------|
| At-most-once | May lose messages | Fire-and-forget; no ack |
| At-least-once | May duplicate | Ack after processing; consumer must be idempotent |
| Exactly-once | No loss, no duplicates | Transactional outbox + idempotent consumer |
Document the chosen guarantee per event/message type in the design doc.
---
## 4. Failure Isolation
### Blast Radius Analysis
For each service dependency, document:
- **Classification:** Critical (service cannot function without it) vs Non-critical (degraded operation acceptable)
- **Failure impact:** What user-visible behavior changes when this dependency fails
- **Isolation mechanism:** How the failure is contained (circuit breaker, bulkhead, fallback)
### Bulkhead Pattern
- Isolate resources per dependency: separate thread pools, connection pools, or rate limiters
- A slow dependency should not exhaust resources needed by other dependencies
- Size bulkheads based on expected call volume and timeout settings
### Dependency Classification Template
```yaml
dependencies:
- name: "payment-service"
type: sync | async
classification: critical | non-critical
timeout_ms: 3000
retry: {max: 3, backoff: exponential, base_ms: 100}
circuit_breaker: {threshold: 5, open_duration_ms: 30000}
fallback: "Queue payment for async processing"
blast_radius: "Orders cannot be completed; items remain in cart"
```
---
## AI-Enforceable Checks
Applied during design review by tpm-quality agent.
| ID | Check | Severity | Detection |
|----|-------|----------|-----------|
| SB-01 | Every entity has a documented owning service/context | P1 | Entity referenced without ownership statement |
| SB-02 | No direct database writes from non-owning services | P0 | Service writing to another service's tables |
| SB-03 | Every sync dependency has timeout, retry, circuit breaker, and fallback specified | P0 | Sync dependency without any of these four fields |
| SB-04 | Async events have delivery guarantee documented | P1 | Event/message definition without at-most/at-least/exactly-once specification |
| SB-05 | Every dependency classified as critical or non-critical with blast radius documented | P1 | Dependency listed without classification or failure impact |
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |