nanotaboada · nanotaboada · Jun 12, 2026 · Jun 10, 2026 · Jun 12, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -44,6 +44,10 @@ This project uses famous football coaches as release codenames, following an A-Z
 
 ### Added
 
+- ADR-0011: Use Coach-Themed Semantic Versioning
+- ADR-0012: Adopt AI-Assisted Development Workflow
+- ADR-0013: Adopt Spec-Driven Development (SDD)
+
 ### Changed
 
 - `CLAUDE.md`: fix stale `docker-compose.yml` reference to `compose.yaml`; add

diff --git a/CLAUDE.md b/CLAUDE.md
@@ -221,6 +221,6 @@ API shape changes → update services and tests → run `pytest`.
 
 ## Architecture Decision Records
 
-Significant architectural decisions are documented in `docs/adr/` (ADR-0001–0010).
+Significant architectural decisions are documented in `docs/adr/` (ADR-0001–0013).
 Load these before proposing structural changes. When a proposal would change an
 accepted decision, create a new ADR rather than editing the existing one.
diff --git a/docs/adr/0011-coach-themed-versioning.md b/docs/adr/0011-coach-themed-versioning.md
@@ -0,0 +1,77 @@
+# ADR-0011: Use Coach-Themed Semantic Versioning
+
+Date: 2026-06-10
+
+## Status
+
+Accepted
+
+## Context
+
+The project uses Semantic Versioning (MAJOR.MINOR.PATCH). Purely numeric tags
+are accurate but forgettable. The project is football-themed and part of a
+cross-language comparison set where each repo adopts a different
+football-domain naming convention. Several well-known projects use alphabetical
+codename conventions (Ubuntu, Android).
+
+This repo uses famous football managers/coaches as codenames. Release tags
+follow the format `v{MAJOR}.{MINOR}.{PATCH}-{coach}`, where the coach name is
+drawn from the fixed list below, assigned A→Z sequentially:
+
+| Letter | Coach Name | Country/Notable Era | Tag Name |
+| ------ | ---------- | ------------------- | -------- |
+| A | Ancelotti (Carlo) | Italy | `ancelotti` |
+| B | Bielsa (Marcelo) | Argentina | `bielsa` |
+| C | Capello (Fabio) | Italy | `capello` |
+| D | Del Bosque (Vicente) | Spain | `delbosque` |
+| E | Eriksson (Sven-Göran) | Sweden | `eriksson` |
+| F | Ferguson (Alex) | Scotland | `ferguson` |
+| G | Guardiola (Pep) | Spain | `guardiola` |
+| H | Heynckes (Jupp) | Germany | `heynckes` |
+| I | Inzaghi (Simone) | Italy | `inzaghi` |
+| J | Klopp (Jürgen) | Germany | `klopp` |
+| K | Kovač (Niko) | Croatia | `kovac` |
+| L | Löw (Joachim) | Germany | `low` |
+| M | Mourinho (José) | Portugal | `mourinho` |
+| N | Nagelsmann (Julian) | Germany | `nagelsmann` |
+| O | Ottmar Hitzfeld | Germany/Switzerland | `ottmar` |
+| P | Pochettino (Mauricio) | Argentina | `pochettino` |
+| Q | Queiroz (Carlos) | Portugal | `queiroz` |
+| R | Ranieri (Claudio) | Italy | `ranieri` |
+| S | Simeone (Diego) | Argentina | `simeone` |
+| T | Tuchel (Thomas) | Germany | `tuchel` |
+| U | Unai Emery | Spain | `unai` |
+| V | Van Gaal (Louis) | Netherlands | `vangaal` |
+| W | Wenger (Arsène) | France | `wenger` |
+| X | Xavi Hernández | Spain | `xavi` |
+| Y | Yozhef Sabo | Ukraine | `yozhef` |
+| Z | Zeman (Zdeněk) | Czech Republic | `zeman` |
+
+## Decision
+
+Every release tag appends an alphabetically ordered football coach surname to
+the Semantic Version. Format: `v{MAJOR}.{MINOR}.{PATCH}-{coach}`. Names are
+drawn from the fixed list above, assigned A→Z sequentially. The CD pipeline
+validates the coach name against this list before publishing.
+
+## Consequences
+
+**Positive:**
+
+- Release names are memorable and human-friendly.
+- Alphabetical ordering provides an implicit sequence visible in `git tag`.
+- The naming scheme is deterministic — the next name is always the next letter.
+- Reinforces the football theme across the cross-language comparison set.
+
+**Negative:**
+
+- Non-standard tag format; may confuse new contributors unfamiliar with the
+  convention.
+- The list is finite — 26 slots before the sequence must restart or be
+  extended.
+- CD validation adds a small amount of pipeline complexity.
+
+**Neutral:**
+
+- The full list is documented in `CLAUDE.md` and `CHANGELOG.md`; the current
+  position is always the last released tag.
diff --git a/docs/adr/0012-ai-assisted-development-workflow.md b/docs/adr/0012-ai-assisted-development-workflow.md
@@ -0,0 +1,76 @@
+# ADR-0012: Adopt AI-Assisted Development Workflow
+
+Date: 2026-06-10
+
+## Status
+
+Accepted
+
+## Context
+
+Software development has historically relied on three successive layers
+of knowledge:
+
+1. **Official documentation** — authoritative but static; describes the
+   intended API but not how real projects apply it
+2. **Community collaboration** — Stack Overflow, GitHub Discussions, blog
+   posts; describes how practitioners actually solve problems, but requires
+   the developer to synthesize and apply that knowledge themselves
+3. **AI synthesis** — models trained on both layers above, capable of
+   applying idiomatic, stack-specific knowledge directly to a given
+   codebase
+
+Agentic AI tools represent a qualitative shift: instead of consulting
+knowledge and applying it manually, the developer delegates implementation
+to an agent that has absorbed the collective idioms of a stack — "the
+Microsoft way", "the FastAPI way" — and can apply them consistently.
+
+For a cross-language REST API comparison project, this matters
+particularly: each implementation should reflect how an experienced
+practitioner in that stack would structure the same problem, not a
+generic approach that happens to compile.
+
+Prior to Claude Code, AI assistance was used ad-hoc — pasting code into
+web interfaces (ChatGPT, DeepSeek) or via IDE-integrated assistants
+(GitHub Copilot). Both approaches lack persistent codebase context and
+the ability to act autonomously across a project.
+
+## Decision
+
+We adopt Claude Code as the primary development workflow tool for this
+project.
+
+A `CLAUDE.md` file at the repository root serves as the workflow
+specification: it documents architecture, coding conventions, invariants,
+and explicit boundaries for autonomous operation — what the agent may do
+freely, what requires human approval, and what must never be changed.
+
+CodeRabbit provides an additional automated code review layer
+independent of the primary workflow.
+
+## Consequences
+
+**Positive:**
+
+- Stack-specific idioms are enforced by the agent's collective knowledge
+  rather than individual developer discipline
+- `CLAUDE.md` is living architectural documentation: it must stay
+  accurate for the workflow to function, creating a natural incentive to
+  keep it current
+- Explicit autonomy boundaries make human oversight intentional rather
+  than incidental
+
+**Negative:**
+
+- Token economics: long-running work may exceed context limits, requiring
+  active session management and continuation prompts to resume work
+  across sessions
+- The global `~/.claude/CLAUDE.md` and per-repo `CLAUDE.md` must stay
+  aligned; drift between them produces inconsistent agent behavior
+
+**Neutral:**
+
+- Development workflow moves to the terminal/CLI rather than an IDE;
+  this has no impact on the codebase itself
+- `CLAUDE.md` is specific to Claude Code; a different tool would require
+  a different workflow specification format
diff --git a/docs/adr/0013-spec-driven-development.md b/docs/adr/0013-spec-driven-development.md
@@ -0,0 +1,61 @@
+# ADR-0013: Adopt Spec-Driven Development (SDD)
+
+Date: 2026-06-10
+
+## Status
+
+Accepted
+
+## Context
+
+In an agentic development workflow, it is easy to begin implementation
+before requirements are fully understood. An AI assistant will produce
+working code from a vague prompt — but working and correct are not the
+same thing. Without a forcing function that requires requirements to be
+stated explicitly before implementation begins, scope creep, rework, and
+misaligned implementations are likely outcomes.
+
+GitHub Issues provide a natural spec artifact: persistent, linkable,
+and — critically — they survive session boundaries. In a workflow where
+context is lost between sessions, an Issue that captures the agreed
+approach and acceptance criteria before implementation begins serves as
+the durable contract between intent and implementation.
+
+## Decision
+
+All new features and non-trivial changes follow a three-step workflow:
+
+1. **Discuss** — describe the requirement in Claude Code Plan mode;
+   explore alternatives and consequences before committing to an approach
+2. **Specify** — create a GitHub Issue as the spec artifact, capturing
+   the agreed approach, acceptance criteria, and any constraints
+3. **Implement** — work against the Issue; commits reference it via
+   the `(#issue)` suffix in the Conventional Commits format
+
+Trivial changes (documentation updates, formatting fixes, dependency
+bumps) may skip the Issue step at the developer's discretion.
+
+## Consequences
+
+**Positive:**
+
+- Requirements are stated explicitly before implementation; the agent
+  works against a written spec rather than an interpreted prompt
+- Issues survive session boundaries — a new session can resume from
+  the Issue rather than reconstructing intent from scratch
+- The implementation trail (Issue → branch → PR → commit) is traceable
+  without relying on session memory
+
+**Negative:**
+
+- Adds upfront overhead for changes that feel small; the Issue step can
+  seem bureaucratic for straightforward work
+- The line between "spec-worthy" and "trivial" is judgment-dependent
+  and not enforced by tooling
+
+**Neutral:**
+
+- GitHub Issues double as the project backlog; SDD and backlog
+  management share the same artifact
+- Plan mode discussion is ephemeral — not persisted outside the session;
+  the Issue is the only durable record of the pre-implementation reasoning
diff --git a/docs/adr/README.md b/docs/adr/README.md
@@ -22,3 +22,6 @@ one and the three-part test.
 | [0008](0008-layered-architecture.md) | Layered Architecture with FastAPI Dependency Injection | Accepted | 2026-04-02 |
 | [0009](0009-docker-and-compose-strategy.md) | Docker and Compose Strategy | Accepted | 2026-04-02 |
 | [0010](0010-alembic-migration-based-schema-management.md) | Alembic Migration-Based Schema Management | Accepted | 2026-04-09 |
+| [0011](0011-coach-themed-versioning.md) | Use Coach-Themed Semantic Versioning | Accepted | 2026-06-10 |
+| [0012](0012-ai-assisted-development-workflow.md) | Adopt AI-Assisted Development Workflow | Accepted | 2026-06-10 |
+| [0013](0013-spec-driven-development.md) | Adopt Spec-Driven Development (SDD) | Accepted | 2026-06-10 |