From 5e5eff0c6b1ab04e4a6974a18471523d6f46401d Mon Sep 17 00:00:00 2001 From: Nano Taboada Date: Wed, 10 Jun 2026 14:04:48 -0300 Subject: [PATCH 1/2] docs(adr): add themed versioning, AI workflow and SDD records Co-authored-by: Claude Sonnet 4.6 --- CHANGELOG.md | 4 + CLAUDE.md | 2 +- docs/adr/0011-coach-themed-versioning.md | 77 +++++++++++++++++++ .../0012-ai-assisted-development-workflow.md | 76 ++++++++++++++++++ docs/adr/0013-spec-driven-development.md | 61 +++++++++++++++ docs/adr/README.md | 3 + 6 files changed, 222 insertions(+), 1 deletion(-) create mode 100644 docs/adr/0011-coach-themed-versioning.md create mode 100644 docs/adr/0012-ai-assisted-development-workflow.md create mode 100644 docs/adr/0013-spec-driven-development.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 51237fe..b1b4ef3 100644 --- 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 index 817a708..a424372 100644 --- 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 new file mode 100644 index 0000000..7793980 --- /dev/null +++ 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, macOS). + +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 new file mode 100644 index 0000000..ebbe035 --- /dev/null +++ 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 new file mode 100644 index 0000000..eba4207 --- /dev/null +++ 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 index 2b329c0..9698d64 100644 --- 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 | From 307fb6815b7e519416c33e895de459e8498977db Mon Sep 17 00:00:00 2001 From: Nano Taboada Date: Thu, 11 Jun 2026 23:53:26 -0300 Subject: [PATCH 2/2] docs(adr): fix macOS codename example in ADR-0011 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit macOS uses California landmark names, not alphabetical codenames. Replace with Android (A→P dessert names) as the correct example. Co-authored-by: Claude Sonnet 4.6 --- docs/adr/0011-coach-themed-versioning.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/adr/0011-coach-themed-versioning.md b/docs/adr/0011-coach-themed-versioning.md index 7793980..4ccda73 100644 --- a/docs/adr/0011-coach-themed-versioning.md +++ b/docs/adr/0011-coach-themed-versioning.md @@ -12,7 +12,7 @@ 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, macOS). +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