antigravity-skills-reference/skills/uncle-bob-craft/reference.md

# Uncle Bob Craft — Expanded Reference

This document expands the criteria referenced in the main skill. Sources: *Clean Code*, *Clean Architecture*, *The Clean Coder*, *Clean Agile* (Robert C. Martin). Use for progressive disclosure when you need full lists or deeper context.

---

## Clean Architecture

### Dependency Rule

Source code dependencies must point only **inward** (toward higher-level policies). Inner layers do not know about outer layers (e.g., use cases do not import from the web framework or the database driver).

- **Entities** (enterprise business rules) — center, no outward dependencies.
- **Use cases** (application business rules) — depend only on entities.
- **Interface adapters** (presenters, gateways) — depend on use cases/entities.
- **Frameworks and drivers** (UI, DB, HTTP) — outermost; depend inward.

### Layers (hexagonal / ports and adapters)

| Layer | Responsibility | Depends on |
|-------|----------------|------------|
| Entities | Core business entities and rules | Nothing (innermost) |
| Use cases | Application-specific business rules, orchestration | Entities |
| Interface adapters | Convert data between use cases and external world | Use cases, entities |
| Frameworks & drivers | DB, UI, HTTP, file I/O | Interface adapters |

### SOLID in architecture context

- **SRP** — A module should have one reason to change (one actor).
- **OCP** — Open for extension, closed for modification (use abstractions and boundaries).
- **LSP** — Subtypes must be substitutable for their base types (interfaces and implementations).
- **ISP** — Many client-specific interfaces are better than one general-purpose interface (splitting interfaces at boundaries).
- **DIP** — Depend on abstractions, not concretions (invert dependencies at boundaries).

### Component design (summary)

For grouping classes into components: **REP** (reuse/release equivalence), **CCP** (common closure), **CRP** (common reuse); **ADP** (acyclic dependencies), **SDP** (stable dependencies), **SAP** (stable abstractions). See [references/clean-architecture.md](./references/clean-architecture.md) for brief definitions.

---

## The Clean Coder

### Professionalism

- **Do no harm** — Do not leave the code worse than you found it; leave it better when you can.
- **Work ethic** — Know your craft, practice, stay current.
- **Saying no** — Say no when the request is unreasonable or would compromise quality; offer alternatives.
- **Saying yes** — When you say yes, mean it; commit to deadlines you can meet.

### Estimation

- **Three-point estimates** — Best case, nominal, worst case; use for planning, not promises.
- **Velocity** — Use historical velocity for iteration planning; do not inflate commitments.
- **Uncertainty** — Communicate uncertainty; avoid false precision.

### Sustainable pace

- Avoid sustained overtime; it reduces quality and long-term output.
- Tests and refactoring are part of the job, not "extra."

### Tests as requirement

- Code without tests is legacy by definition. Writing tests is a professional requirement.

### Mentoring and collaboration

- Helping others (mentoring, pairing) and leaving the team and codebase better are part of professionalism.

---

## Clean Agile

### Values (from Agile manifesto, emphasized by Uncle Bob)

- Individuals and interactions over processes and tools.
- Working software over comprehensive documentation.
- Customer collaboration over contract negotiation.
- Responding to change over following a plan.

### Iron Cross (four values that support the above)

| Value | Meaning |
|-------|--------|
| **Communication** | Prefer face-to-face and collaboration; reduce information loss. |
| **Courage** | Courage to refactor, to say no, to change design when needed. |
| **Feedback** | Short feedback loops (tests, demos, iterations). |
| **Simplicity** | Do the simplest thing that could work; avoid speculative design. |

### Practices

- **TDD** — Red, green, refactor; tests first as specification and safety net.
- **Refactoring** — Continuous small improvements; keep tests green.
- **Pair programming** — Two people at one machine; design and quality improve.
- **Simple design** — No duplication, express intent, minimal elements, small abstractions.

---

## Smells and Heuristics (expanded)

### Design smells (from Clean Code / Clean Architecture)

| Code | Name | Brief |
|------|------|--------|
| **Rigidity** | Hard to change; one change triggers many. | Reduce coupling; introduce boundaries. |
| **Fragility** | Breaks in unexpected places. | Isolate changes; improve tests. |
| **Immobility** | Hard to reuse. | Extract reusable parts; reduce coupling. |
| **Viscosity** | Easy to hack, hard to do right. | Make right thing easy (abstractions, tests). |
| **Needless complexity** | Speculative or unused design. | YAGNI; remove until needed. |
| **Needless repetition** | DRY violated. | Extract common logic; name the abstraction. |
| **Opacity** | Hard to understand. | Rename, extract, clarify intent. |

### Heuristics (review checklist style)

- **C1 / Naming** — Names reveal intent; no disinformation (e.g., `accountList` when it is not a list).
- **C2 / Functions** — Small, one thing, one level of abstraction; few arguments.
- **C3 / Comments** — Prefer self-explanatory code; good comments for why, not what.
- **C4 / Formatting** — Newspaper metaphor; vertical density; variables near use.
- **C5 / Error handling** — Exceptions over return codes; don’t return or pass null without contract.
- **C6 / Tests** — F.I.R.S.T.; TDD when applicable.
- **C7 / Classes** — Small, single responsibility; stepdown rule.
- **T1 / Boundaries** — Dependencies point inward; no outer details in inner layers.
- **T2 / SOLID** — Check SRP, OCP, LSP, ISP, DIP in context.
- **T3 / Patterns** — Pattern used to solve a real problem, not for show.

(You can extend to a full C1–T9 list in your team; the above is a compact reference.)

---

## Design patterns (when and when not)

- **Use** when: you have repeated variation (Strategy), lifecycle/creation complexity (Factory), or a clear cross-cutting concern (e.g., logging, validation at a boundary).
- **Avoid** when: the code is simple and a pattern would add indirection without reducing duplication or clarifying intent.
- **Cargo cult** — Applying a pattern by name everywhere (e.g., everything is a Factory) without a design reason. Prefer "simplest thing that could work" until duplication or change axis appears.

---

---

## Scope and attribution

- **Clean Code** — Full heuristics and chapter-by-chapter detail: use the `@clean-code` skill. This skill references Clean Code for review context and defers naming/functions/formatting there.
- **Clean Architecture** — We cover the Dependency Rule, layers, boundaries, SOLID in architecture, and component cohesion/coupling (REP, CCP, CRP, ADP, SDP, SAP) in summary; the book has full treatment and more nuance.
- **The Clean Coder** — We summarize professionalism, estimation, sustainable pace, tests, and mentoring; the book has full chapters and stories.
- **Clean Agile** — We summarize values, Iron Cross, and key practices (TDD, refactoring, pairing, simple design); the book ties them to agile history and adoption.

*Attribution: Principles and structure drawn from Robert C. Martin, Clean Code (2008), Clean Architecture (2017), The Clean Coder (2011), Clean Agile (2019). This reference is a summary for agent use, not a substitute for the books.*