From 7e06760eb6cb72e7394c06c329fe9666d0e02f3b Mon Sep 17 00:00:00 2001 From: Nano Taboada <87288+nanotaboada@users.noreply.github.com> Date: Thu, 11 Jun 2026 23:49:08 -0300 Subject: [PATCH 1/2] docs(adr): add themed versioning, AI workflow and SDD records Co-authored-by: Claude Sonnet 4.6 --- .claude/commands/pre-commit.md | 9 ++- CHANGELOG.md | 6 +- CLAUDE.md | 23 +++--- ...0001-adopt-rocket-as-rest-api-framework.md | 0 .../adr}/0002-four-layer-architecture.md | 0 .../adr}/0003-diesel-r2d2-bundled-sqlite.md | 0 ...uuid-surrogate-squad-number-natural-key.md | 0 .../adr}/0005-full-replace-put-no-patch.md | 0 .../0006-embed-migrations-startup-schema.md | 0 .../0007-integration-only-test-strategy.md | 0 .../adr}/0008-docker-compose-strategy.md | 0 docs/adr/0009-ballon-dor-themed-versioning.md | 56 ++++++++++++++ .../0010-ai-assisted-development-workflow.md | 76 +++++++++++++++++++ docs/adr/0011-spec-driven-development.md | 61 +++++++++++++++ {adr => docs/adr}/README.md | 3 + {adr => docs/adr}/template.md | 0 16 files changed, 219 insertions(+), 15 deletions(-) rename {adr => docs/adr}/0001-adopt-rocket-as-rest-api-framework.md (100%) rename {adr => docs/adr}/0002-four-layer-architecture.md (100%) rename {adr => docs/adr}/0003-diesel-r2d2-bundled-sqlite.md (100%) rename {adr => docs/adr}/0004-uuid-surrogate-squad-number-natural-key.md (100%) rename {adr => docs/adr}/0005-full-replace-put-no-patch.md (100%) rename {adr => docs/adr}/0006-embed-migrations-startup-schema.md (100%) rename {adr => docs/adr}/0007-integration-only-test-strategy.md (100%) rename {adr => docs/adr}/0008-docker-compose-strategy.md (100%) create mode 100644 docs/adr/0009-ballon-dor-themed-versioning.md create mode 100644 docs/adr/0010-ai-assisted-development-workflow.md create mode 100644 docs/adr/0011-spec-driven-development.md rename {adr => docs/adr}/README.md (85%) rename {adr => docs/adr}/template.md (100%) diff --git a/.claude/commands/pre-commit.md b/.claude/commands/pre-commit.md index ff6e8b5..1a5f6de 100644 --- a/.claude/commands/pre-commit.md +++ b/.claude/commands/pre-commit.md @@ -10,12 +10,13 @@ Run the pre-commit checklist for this project: 2. Run `cargo fmt` — formats code in place. 3. Run `cargo clippy --all-targets --all-features -- -D warnings` — must pass clean. 4. Run `cargo test` — all tests must pass. -5. Run `cargo build` — must succeed. -6. If Docker is running, run `docker compose build` — must succeed with no +5. Run `cargo tarpaulin --fail-under 80` — coverage must be ≥80%. +6. Run `cargo build` — must succeed. +7. If Docker is running, run `docker compose build` — must succeed with no errors. Skip this step with a note if Docker Desktop is not running. -7. If `coderabbit` CLI is installed, run `coderabbit review --type uncommitted --prompt-only`: +8. If `coderabbit` CLI is installed, run `coderabbit review --type uncommitted --prompt-only`: - If actionable/serious findings are reported, stop and address them before proposing the commit. - If only nitpick-level findings, report them and continue to the commit proposal. - If `coderabbit` is not installed, skip this step with a note. -Run steps 2–5, run step 6 (docker build), then run step 7 (CodeRabbit review) if available, report the results clearly, then propose a branch name and commit message for my approval using the format `type(scope): description (#issue)` (max 80 chars; types: `feat` `fix` `chore` `docs` `test` `refactor` `ci` `perf`) followed by a co-author line `Co-authored-by: Claude Sonnet 4.6 `. Do not create the branch or commit until I explicitly confirm. +Run steps 2–6, run step 7 (docker build), then run step 8 (CodeRabbit review) if available, report the results clearly, then propose a branch name and commit message for my approval using the format `type(scope): description (#issue)` (max 80 chars; types: `feat` `fix` `chore` `docs` `test` `refactor` `ci` `perf`) followed by a co-author line `Co-authored-by: Claude Sonnet 4.6 `. Do not create the branch or commit until I explicitly confirm. diff --git a/CHANGELOG.md b/CHANGELOG.md index f4f3a65..c14f3ac 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -44,13 +44,17 @@ Release codenames follow an A-Z sequence using Ballon d'Or award nominees surnam ### Added -- Architecture Decision Records in `adr/`: 8 ADRs (0001–0008) documenting framework selection, four-layer architecture, Diesel/r2d2/SQLite persistence stack, dual-key strategy, PUT semantics, embedded migrations, integration-only testing, and Docker/Compose strategy (`#113`) +- Architecture Decision Records in `docs/adr/`: 8 ADRs (0001–0008) documenting framework selection, four-layer architecture, Diesel/r2d2/SQLite persistence stack, dual-key strategy, PUT semantics, embedded migrations, integration-only testing, and Docker/Compose strategy (`#113`) +- ADR-0009: Use Ballon d'Or-Themed Semantic Versioning +- ADR-0010: Adopt AI-Assisted Development Workflow +- ADR-0011: Adopt Spec-Driven Development (SDD) ### Changed - Replace `cargo install cargo-tarpaulin` with `taiki-e/install-action@v2.81.8` in CI to use a pre-built binary and reduce coverage job runtime - Consolidated agent instructions from `.github/copilot-instructions.md` into `CLAUDE.md`; deleted the legacy split-file layout (`#112`) - Rewrote all stale `.coderabbit.yaml` path instructions to reflect the current Diesel/r2d2/SQLite architecture; removed all references to the old `Mutex>` in-memory design (`#112`) +- Added `cargo tarpaulin --fail-under 80` to the `/pre-commit` checklist to enforce 80% coverage locally ### Fixed diff --git a/CLAUDE.md b/CLAUDE.md index e38ac9f..54162b9 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -70,7 +70,7 @@ cargo test -- --nocapture # with output 3. `cargo build` — must succeed 4. `cargo test` — all tests must pass 5. Commit message follows Conventional Commits format (enforced by commitlint) -6. If this commit introduces or changes an architectural decision, update `CLAUDE.md` and create or amend the relevant ADR in `adr/`. +6. If this commit introduces or changes an architectural decision, update `CLAUDE.md` and create or amend the relevant ADR in `docs/adr/`. 7. If this commit adds, removes, or changes an endpoint, a dependency, or how the project is run, update `README.md` and the relevant path instructions in `.coderabbit.yaml`. ### Commits @@ -148,20 +148,23 @@ Co-authored-by: Claude Sonnet 4.6 ## Architecture Decision Records -Architectural decisions are documented in `adr/`. When proposing structural +Architectural decisions are documented in [`docs/adr/`](docs/adr/README.md). When proposing structural changes, check the ADR index first. When a decision changes, mark the existing ADR as `Deprecated` or `Superseded by ADR-XXXX` and write a new one. Current ADRs: -- [ADR-0001](adr/0001-adopt-rocket-as-rest-api-framework.md) — Rocket 0.5 as HTTP framework -- [ADR-0002](adr/0002-four-layer-architecture.md) — Routes → Services → Repositories → State -- [ADR-0003](adr/0003-diesel-r2d2-bundled-sqlite.md) — Diesel + r2d2 + bundled libsqlite3 -- [ADR-0004](adr/0004-uuid-surrogate-squad-number-natural-key.md) — UUID surrogate key + squad number natural key -- [ADR-0005](adr/0005-full-replace-put-no-patch.md) — Full-replace PUT, no PATCH -- [ADR-0006](adr/0006-embed-migrations-startup-schema.md) — `embed_migrations!()` at startup -- [ADR-0007](adr/0007-integration-only-test-strategy.md) — Integration-only tests with in-memory SQLite -- [ADR-0008](adr/0008-docker-compose-strategy.md) — Multi-stage Dockerfile + Compose +- [ADR-0001](docs/adr/0001-adopt-rocket-as-rest-api-framework.md) — Rocket 0.5 as HTTP framework +- [ADR-0002](docs/adr/0002-four-layer-architecture.md) — Routes → Services → Repositories → State +- [ADR-0003](docs/adr/0003-diesel-r2d2-bundled-sqlite.md) — Diesel + r2d2 + bundled libsqlite3 +- [ADR-0004](docs/adr/0004-uuid-surrogate-squad-number-natural-key.md) — UUID surrogate key + squad number natural key +- [ADR-0005](docs/adr/0005-full-replace-put-no-patch.md) — Full-replace PUT, no PATCH +- [ADR-0006](docs/adr/0006-embed-migrations-startup-schema.md) — `embed_migrations!()` at startup +- [ADR-0007](docs/adr/0007-integration-only-test-strategy.md) — Integration-only tests with in-memory SQLite +- [ADR-0008](docs/adr/0008-docker-compose-strategy.md) — Multi-stage Dockerfile + Compose +- [ADR-0009](docs/adr/0009-ballon-dor-themed-versioning.md) — Ballon d'Or-themed release codenames +- [ADR-0010](docs/adr/0010-ai-assisted-development-workflow.md) — Claude Code as primary workflow tool +- [ADR-0011](docs/adr/0011-spec-driven-development.md) — Spec-Driven Development (SDD) ## Claude Code diff --git a/adr/0001-adopt-rocket-as-rest-api-framework.md b/docs/adr/0001-adopt-rocket-as-rest-api-framework.md similarity index 100% rename from adr/0001-adopt-rocket-as-rest-api-framework.md rename to docs/adr/0001-adopt-rocket-as-rest-api-framework.md diff --git a/adr/0002-four-layer-architecture.md b/docs/adr/0002-four-layer-architecture.md similarity index 100% rename from adr/0002-four-layer-architecture.md rename to docs/adr/0002-four-layer-architecture.md diff --git a/adr/0003-diesel-r2d2-bundled-sqlite.md b/docs/adr/0003-diesel-r2d2-bundled-sqlite.md similarity index 100% rename from adr/0003-diesel-r2d2-bundled-sqlite.md rename to docs/adr/0003-diesel-r2d2-bundled-sqlite.md diff --git a/adr/0004-uuid-surrogate-squad-number-natural-key.md b/docs/adr/0004-uuid-surrogate-squad-number-natural-key.md similarity index 100% rename from adr/0004-uuid-surrogate-squad-number-natural-key.md rename to docs/adr/0004-uuid-surrogate-squad-number-natural-key.md diff --git a/adr/0005-full-replace-put-no-patch.md b/docs/adr/0005-full-replace-put-no-patch.md similarity index 100% rename from adr/0005-full-replace-put-no-patch.md rename to docs/adr/0005-full-replace-put-no-patch.md diff --git a/adr/0006-embed-migrations-startup-schema.md b/docs/adr/0006-embed-migrations-startup-schema.md similarity index 100% rename from adr/0006-embed-migrations-startup-schema.md rename to docs/adr/0006-embed-migrations-startup-schema.md diff --git a/adr/0007-integration-only-test-strategy.md b/docs/adr/0007-integration-only-test-strategy.md similarity index 100% rename from adr/0007-integration-only-test-strategy.md rename to docs/adr/0007-integration-only-test-strategy.md diff --git a/adr/0008-docker-compose-strategy.md b/docs/adr/0008-docker-compose-strategy.md similarity index 100% rename from adr/0008-docker-compose-strategy.md rename to docs/adr/0008-docker-compose-strategy.md diff --git a/docs/adr/0009-ballon-dor-themed-versioning.md b/docs/adr/0009-ballon-dor-themed-versioning.md new file mode 100644 index 0000000..ffadafa --- /dev/null +++ b/docs/adr/0009-ballon-dor-themed-versioning.md @@ -0,0 +1,56 @@ +# ADR-0009: Use Ballon d'Or-Themed Semantic Versioning + +Date: 2026-06-10 + +## Status + +Accepted + +## Context + +The project uses Semantic Versioning (MAJOR.MINOR.PATCH) for release numbers. +Release codenames — appended as a suffix to the version tag — need a convention +that is memorable, consistent within this repository, and thematically +appropriate for a football-domain project. + +Options considered: standard semver only (no names), animal names (arbitrary, +no thematic link), city names (too generic), and names drawn from the football +domain (players, clubs, tournaments). + +Each of the six sibling repositories in the cross-language comparison series +adopts its own football-themed naming category. This repository uses Ballon +d'Or award nominees — one of the sport's most prestigious individual honours. + +## Decision + +Append an alphabetically ordered Ballon d'Or nominee surname to every release +tag. Format: `v{MAJOR}.{MINOR}.{PATCH}-{surname}` (e.g. `v1.0.0-aguero`). + +The full A–Z list is documented in `CHANGELOG.md`. Surnames are assigned +sequentially; the current position is tracked by the last released tag. +The CD pipeline validates the codename against the sequence before publishing. + +## Consequences + +### Positive + +- Alphabetical progression makes release ordering unambiguous at a glance, + independent of dates. +- The Ballon d'Or theme is instantly recognisable in a football-domain project + and carries cultural weight: nominees include multiple World Cup winners and + the sport's most celebrated players. +- The convention is deterministic — the next codename is always known in advance. + +### Negative + +- Non-standard: tooling that expects pure semver tags must be configured to + ignore the suffix. +- The A–Z sequence has 26 slots before a wrap-around or convention change is + needed. +- The CD pipeline must validate codenames, adding a step not present in pure + semver workflows. + +### Neutral + +- The full A–Z list and current position are maintained in `CHANGELOG.md`. +- The codename is purely cosmetic — semver carries the semantic meaning. diff --git a/docs/adr/0010-ai-assisted-development-workflow.md b/docs/adr/0010-ai-assisted-development-workflow.md new file mode 100644 index 0000000..59873ff --- /dev/null +++ b/docs/adr/0010-ai-assisted-development-workflow.md @@ -0,0 +1,76 @@ +# ADR-0010: 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 Rocket 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/0011-spec-driven-development.md b/docs/adr/0011-spec-driven-development.md new file mode 100644 index 0000000..6f7be5a --- /dev/null +++ b/docs/adr/0011-spec-driven-development.md @@ -0,0 +1,61 @@ +# ADR-0011: 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/adr/README.md b/docs/adr/README.md similarity index 85% rename from adr/README.md rename to docs/adr/README.md index c9010bd..359e6e8 100644 --- a/adr/README.md +++ b/docs/adr/README.md @@ -19,6 +19,9 @@ marked `Deprecated` or `Superseded by ADR-XXXX` and a new ADR is written. | [0006](0006-embed-migrations-startup-schema.md) | Embedded Migrations at Startup | Accepted | | [0007](0007-integration-only-test-strategy.md) | Integration-Only Test Strategy | Accepted | | [0008](0008-docker-compose-strategy.md) | Docker and Compose Strategy | Accepted | +| [0009](0009-ballon-dor-themed-versioning.md) | Use Ballon d'Or-Themed Semantic Versioning | Accepted | +| [0010](0010-ai-assisted-development-workflow.md) | Adopt AI-Assisted Development Workflow | Accepted | +| [0011](0011-spec-driven-development.md) | Adopt Spec-Driven Development (SDD) | Accepted | ## Creating a New ADR diff --git a/adr/template.md b/docs/adr/template.md similarity index 100% rename from adr/template.md rename to docs/adr/template.md From 183c6f1b65c3e329ee994222e5f2488e92e196b8 Mon Sep 17 00:00:00 2001 From: Nano Taboada <87288+nanotaboada@users.noreply.github.com> Date: Fri, 12 Jun 2026 00:07:19 -0300 Subject: [PATCH 2/2] docs(changelog): consolidate ADR entries into single Unreleased line Co-authored-by: Claude Sonnet 4.6 --- CHANGELOG.md | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index c14f3ac..9b6a661 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -44,10 +44,7 @@ Release codenames follow an A-Z sequence using Ballon d'Or award nominees surnam ### Added -- Architecture Decision Records in `docs/adr/`: 8 ADRs (0001–0008) documenting framework selection, four-layer architecture, Diesel/r2d2/SQLite persistence stack, dual-key strategy, PUT semantics, embedded migrations, integration-only testing, and Docker/Compose strategy (`#113`) -- ADR-0009: Use Ballon d'Or-Themed Semantic Versioning -- ADR-0010: Adopt AI-Assisted Development Workflow -- ADR-0011: Adopt Spec-Driven Development (SDD) +- Architecture Decision Records in `docs/adr/`: 11 ADRs (0001–0011) documenting framework selection, four-layer architecture, Diesel/r2d2/SQLite persistence stack, dual-key strategy, PUT semantics, embedded migrations, integration-only testing, Docker/Compose strategy, Ballon d'Or-themed versioning, AI-assisted development workflow, and Spec-Driven Development (`#113`) ### Changed