Skip to content

Commit d1e49d2

Browse files
nanotaboadananotaboada
authored
Merge pull request #596 from nanotaboada/docs/adr-0011-0013
docs(adr): add themed versioning, AI workflow and SDD records
2 parents 29dd02c + 307fb68 commit d1e49d2

6 files changed

Lines changed: 222 additions & 1 deletion

File tree

‎CHANGELOG.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -44,6 +44,10 @@ This project uses famous football coaches as release codenames, following an A-Z
4444

4545
### Added
4646

47+
- ADR-0011: Use Coach-Themed Semantic Versioning
48+
- ADR-0012: Adopt AI-Assisted Development Workflow
49+
- ADR-0013: Adopt Spec-Driven Development (SDD)
50+
4751
### Changed
4852

4953
- `CLAUDE.md`: fix stale `docker-compose.yml` reference to `compose.yaml`; add

‎CLAUDE.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -221,6 +221,6 @@ API shape changes → update services and tests → run `pytest`.
221221

222222
## Architecture Decision Records
223223

224-
Significant architectural decisions are documented in `docs/adr/` (ADR-0001–0010).
224+
Significant architectural decisions are documented in `docs/adr/` (ADR-0001–0013).
225225
Load these before proposing structural changes. When a proposal would change an
226226
accepted decision, create a new ADR rather than editing the existing one.

‎docs/adr/0011-coach-themed-versioning.md‎

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
# ADR-0011: Use Coach-Themed Semantic Versioning
2+
3+
Date: 2026-06-10
4+
5+
## Status
6+
7+
Accepted
8+
9+
## Context
10+
11+
The project uses Semantic Versioning (MAJOR.MINOR.PATCH). Purely numeric tags
12+
are accurate but forgettable. The project is football-themed and part of a
13+
cross-language comparison set where each repo adopts a different
14+
football-domain naming convention. Several well-known projects use alphabetical
15+
codename conventions (Ubuntu, Android).
16+
17+
This repo uses famous football managers/coaches as codenames. Release tags
18+
follow the format `v{MAJOR}.{MINOR}.{PATCH}-{coach}`, where the coach name is
19+
drawn from the fixed list below, assigned A→Z sequentially:
20+
21+
| Letter | Coach Name | Country/Notable Era | Tag Name |
22+
| ------ | ---------- | ------------------- | -------- |
23+
| A | Ancelotti (Carlo) | Italy | `ancelotti` |
24+
| B | Bielsa (Marcelo) | Argentina | `bielsa` |
25+
| C | Capello (Fabio) | Italy | `capello` |
26+
| D | Del Bosque (Vicente) | Spain | `delbosque` |
27+
| E | Eriksson (Sven-Göran) | Sweden | `eriksson` |
28+
| F | Ferguson (Alex) | Scotland | `ferguson` |
29+
| G | Guardiola (Pep) | Spain | `guardiola` |
30+
| H | Heynckes (Jupp) | Germany | `heynckes` |
31+
| I | Inzaghi (Simone) | Italy | `inzaghi` |
32+
| J | Klopp (Jürgen) | Germany | `klopp` |
33+
| K | Kovač (Niko) | Croatia | `kovac` |
34+
| L | Löw (Joachim) | Germany | `low` |
35+
| M | Mourinho (José) | Portugal | `mourinho` |
36+
| N | Nagelsmann (Julian) | Germany | `nagelsmann` |
37+
| O | Ottmar Hitzfeld | Germany/Switzerland | `ottmar` |
38+
| P | Pochettino (Mauricio) | Argentina | `pochettino` |
39+
| Q | Queiroz (Carlos) | Portugal | `queiroz` |
40+
| R | Ranieri (Claudio) | Italy | `ranieri` |
41+
| S | Simeone (Diego) | Argentina | `simeone` |
42+
| T | Tuchel (Thomas) | Germany | `tuchel` |
43+
| U | Unai Emery | Spain | `unai` |
44+
| V | Van Gaal (Louis) | Netherlands | `vangaal` |
45+
| W | Wenger (Arsène) | France | `wenger` |
46+
| X | Xavi Hernández | Spain | `xavi` |
47+
| Y | Yozhef Sabo | Ukraine | `yozhef` |
48+
| Z | Zeman (Zdeněk) | Czech Republic | `zeman` |
49+
50+
## Decision
51+
52+
Every release tag appends an alphabetically ordered football coach surname to
53+
the Semantic Version. Format: `v{MAJOR}.{MINOR}.{PATCH}-{coach}`. Names are
54+
drawn from the fixed list above, assigned A→Z sequentially. The CD pipeline
55+
validates the coach name against this list before publishing.
56+
57+
## Consequences
58+
59+
**Positive:**
60+
61+
- Release names are memorable and human-friendly.
62+
- Alphabetical ordering provides an implicit sequence visible in `git tag`.
63+
- The naming scheme is deterministic — the next name is always the next letter.
64+
- Reinforces the football theme across the cross-language comparison set.
65+
66+
**Negative:**
67+
68+
- Non-standard tag format; may confuse new contributors unfamiliar with the
69+
convention.
70+
- The list is finite — 26 slots before the sequence must restart or be
71+
extended.
72+
- CD validation adds a small amount of pipeline complexity.
73+
74+
**Neutral:**
75+
76+
- The full list is documented in `CLAUDE.md` and `CHANGELOG.md`; the current
77+
position is always the last released tag.

‎docs/adr/0012-ai-assisted-development-workflow.md‎

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
# ADR-0012: Adopt AI-Assisted Development Workflow
2+
3+
Date: 2026-06-10
4+
5+
## Status
6+
7+
Accepted
8+
9+
## Context
10+
11+
Software development has historically relied on three successive layers
12+
of knowledge:
13+
14+
1. **Official documentation** — authoritative but static; describes the
15+
intended API but not how real projects apply it
16+
2. **Community collaboration** — Stack Overflow, GitHub Discussions, blog
17+
posts; describes how practitioners actually solve problems, but requires
18+
the developer to synthesize and apply that knowledge themselves
19+
3. **AI synthesis** — models trained on both layers above, capable of
20+
applying idiomatic, stack-specific knowledge directly to a given
21+
codebase
22+
23+
Agentic AI tools represent a qualitative shift: instead of consulting
24+
knowledge and applying it manually, the developer delegates implementation
25+
to an agent that has absorbed the collective idioms of a stack — "the
26+
Microsoft way", "the FastAPI way" — and can apply them consistently.
27+
28+
For a cross-language REST API comparison project, this matters
29+
particularly: each implementation should reflect how an experienced
30+
practitioner in that stack would structure the same problem, not a
31+
generic approach that happens to compile.
32+
33+
Prior to Claude Code, AI assistance was used ad-hoc — pasting code into
34+
web interfaces (ChatGPT, DeepSeek) or via IDE-integrated assistants
35+
(GitHub Copilot). Both approaches lack persistent codebase context and
36+
the ability to act autonomously across a project.
37+
38+
## Decision
39+
40+
We adopt Claude Code as the primary development workflow tool for this
41+
project.
42+
43+
A `CLAUDE.md` file at the repository root serves as the workflow
44+
specification: it documents architecture, coding conventions, invariants,
45+
and explicit boundaries for autonomous operation — what the agent may do
46+
freely, what requires human approval, and what must never be changed.
47+
48+
CodeRabbit provides an additional automated code review layer
49+
independent of the primary workflow.
50+
51+
## Consequences
52+
53+
**Positive:**
54+
55+
- Stack-specific idioms are enforced by the agent's collective knowledge
56+
rather than individual developer discipline
57+
- `CLAUDE.md` is living architectural documentation: it must stay
58+
accurate for the workflow to function, creating a natural incentive to
59+
keep it current
60+
- Explicit autonomy boundaries make human oversight intentional rather
61+
than incidental
62+
63+
**Negative:**
64+
65+
- Token economics: long-running work may exceed context limits, requiring
66+
active session management and continuation prompts to resume work
67+
across sessions
68+
- The global `~/.claude/CLAUDE.md` and per-repo `CLAUDE.md` must stay
69+
aligned; drift between them produces inconsistent agent behavior
70+
71+
**Neutral:**
72+
73+
- Development workflow moves to the terminal/CLI rather than an IDE;
74+
this has no impact on the codebase itself
75+
- `CLAUDE.md` is specific to Claude Code; a different tool would require
76+
a different workflow specification format

‎docs/adr/0013-spec-driven-development.md‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
# ADR-0013: Adopt Spec-Driven Development (SDD)
2+
3+
Date: 2026-06-10
4+
5+
## Status
6+
7+
Accepted
8+
9+
## Context
10+
11+
In an agentic development workflow, it is easy to begin implementation
12+
before requirements are fully understood. An AI assistant will produce
13+
working code from a vague prompt — but working and correct are not the
14+
same thing. Without a forcing function that requires requirements to be
15+
stated explicitly before implementation begins, scope creep, rework, and
16+
misaligned implementations are likely outcomes.
17+
18+
GitHub Issues provide a natural spec artifact: persistent, linkable,
19+
and — critically — they survive session boundaries. In a workflow where
20+
context is lost between sessions, an Issue that captures the agreed
21+
approach and acceptance criteria before implementation begins serves as
22+
the durable contract between intent and implementation.
23+
24+
## Decision
25+
26+
All new features and non-trivial changes follow a three-step workflow:
27+
28+
1. **Discuss** — describe the requirement in Claude Code Plan mode;
29+
explore alternatives and consequences before committing to an approach
30+
2. **Specify** — create a GitHub Issue as the spec artifact, capturing
31+
the agreed approach, acceptance criteria, and any constraints
32+
3. **Implement** — work against the Issue; commits reference it via
33+
the `(#issue)` suffix in the Conventional Commits format
34+
35+
Trivial changes (documentation updates, formatting fixes, dependency
36+
bumps) may skip the Issue step at the developer's discretion.
37+
38+
## Consequences
39+
40+
**Positive:**
41+
42+
- Requirements are stated explicitly before implementation; the agent
43+
works against a written spec rather than an interpreted prompt
44+
- Issues survive session boundaries — a new session can resume from
45+
the Issue rather than reconstructing intent from scratch
46+
- The implementation trail (Issue → branch → PR → commit) is traceable
47+
without relying on session memory
48+
49+
**Negative:**
50+
51+
- Adds upfront overhead for changes that feel small; the Issue step can
52+
seem bureaucratic for straightforward work
53+
- The line between "spec-worthy" and "trivial" is judgment-dependent
54+
and not enforced by tooling
55+
56+
**Neutral:**
57+
58+
- GitHub Issues double as the project backlog; SDD and backlog
59+
management share the same artifact
60+
- Plan mode discussion is ephemeral — not persisted outside the session;
61+
the Issue is the only durable record of the pre-implementation reasoning

‎docs/adr/README.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,3 +22,6 @@ one and the three-part test.
2222
| [0008](0008-layered-architecture.md) | Layered Architecture with FastAPI Dependency Injection | Accepted | 2026-04-02 |
2323
| [0009](0009-docker-and-compose-strategy.md) | Docker and Compose Strategy | Accepted | 2026-04-02 |
2424
| [0010](0010-alembic-migration-based-schema-management.md) | Alembic Migration-Based Schema Management | Accepted | 2026-04-09 |
25+
| [0011](0011-coach-themed-versioning.md) | Use Coach-Themed Semantic Versioning | Accepted | 2026-06-10 |
26+
| [0012](0012-ai-assisted-development-workflow.md) | Adopt AI-Assisted Development Workflow | Accepted | 2026-06-10 |
27+
| [0013](0013-spec-driven-development.md) | Adopt Spec-Driven Development (SDD) | Accepted | 2026-06-10 |

0 commit comments

Comments
 (0)