From d33d04adfa2b854ad9050004e9035c0035de4331 Mon Sep 17 00:00:00 2001 From: Nano Taboada Date: Wed, 10 Jun 2026 08:58:40 -0300 Subject: [PATCH 1/2] docs(adr): add AI workflow and SDD decision records Co-authored-by: Claude Sonnet 4.6 --- CHANGELOG.md | 2 + CLAUDE.md | 2 +- .../0013-ai-assisted-development-workflow.md | 73 +++++++++++++++++++ docs/adr/0014-spec-driven-development.md | 58 +++++++++++++++ docs/adr/README.md | 2 + 5 files changed, 136 insertions(+), 1 deletion(-) create mode 100644 docs/adr/0013-ai-assisted-development-workflow.md create mode 100644 docs/adr/0014-spec-driven-development.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 955f8a9..cdbc4d8 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -43,6 +43,8 @@ Release names follow the **historic football clubs** naming convention (A–Z): ### Added - Architecture Decision Records (ADRs) documenting 12 architectural decisions in `docs/adr/` (#299) +- ADR-0013: Adopt AI-Assisted Development Workflow +- ADR-0014: Adopt Spec-Driven Development (SDD) ### Changed diff --git a/CLAUDE.md b/CLAUDE.md index bec05dd..8520527 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -161,7 +161,7 @@ When a decision changes, update this file and create or amend the relevant ADR. ## Additional Resources -- **Architecture Decision Records**: [`docs/adr/`](docs/adr/README.md) — 12 ADRs documenting the "why" behind major architectural and technology choices in this project. +- **Architecture Decision Records**: [`docs/adr/`](docs/adr/README.md) — 14 ADRs documenting the "why" behind major architectural and technology choices in this project. - New architecturally significant decisions (framework changes, persistence strategy, API contract changes, test strategy shifts) should include a new ADR in `docs/adr/` following the template in [`docs/adr/template.md`](docs/adr/template.md). ## Claude Code diff --git a/docs/adr/0013-ai-assisted-development-workflow.md b/docs/adr/0013-ai-assisted-development-workflow.md new file mode 100644 index 0000000..63a0894 --- /dev/null +++ b/docs/adr/0013-ai-assisted-development-workflow.md @@ -0,0 +1,73 @@ +# ADR-0013: 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 Spring Boot 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/0014-spec-driven-development.md b/docs/adr/0014-spec-driven-development.md new file mode 100644 index 0000000..1829d76 --- /dev/null +++ b/docs/adr/0014-spec-driven-development.md @@ -0,0 +1,58 @@ +# ADR-0014: 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 cb4add4..4707edd 100644 --- a/docs/adr/README.md +++ b/docs/adr/README.md @@ -20,6 +20,8 @@ An ADR documents a single decision: the context that drove it, the alternatives | [ADR-0010](0010-full-replace-put-no-patch.md) | Full-Replace PUT, No PATCH | Accepted | | [ADR-0011](0011-mixed-test-strategy.md) | Mixed Test Strategy | Accepted | | [ADR-0012](0012-adopt-flyway-migrations.md) | Adopt Flyway for Database Migrations | Accepted | +| [ADR-0013](0013-ai-assisted-development-workflow.md) | Adopt AI-Assisted Development Workflow | Accepted | +| [ADR-0014](0014-spec-driven-development.md) | Adopt Spec-Driven Development (SDD) | Accepted | ## Resources From 48e5a795b54b8ca8ce0061849906c99d491b11d7 Mon Sep 17 00:00:00 2001 From: Nano Taboada Date: Wed, 10 Jun 2026 13:50:01 -0300 Subject: [PATCH 2/2] fix(docs): add blank lines after ADR subsection headings (MD022) Co-authored-by: Claude Sonnet 4.6 --- CHANGELOG.md | 4 ++-- docs/adr/0013-ai-assisted-development-workflow.md | 3 +++ docs/adr/0014-spec-driven-development.md | 3 +++ 3 files changed, 8 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index cdbc4d8..010733c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -43,8 +43,8 @@ Release names follow the **historic football clubs** naming convention (A–Z): ### Added - Architecture Decision Records (ADRs) documenting 12 architectural decisions in `docs/adr/` (#299) -- ADR-0013: Adopt AI-Assisted Development Workflow -- ADR-0014: Adopt Spec-Driven Development (SDD) +- ADR-0013: Adopt AI-Assisted Development Workflow (#342) +- ADR-0014: Adopt Spec-Driven Development (SDD) (#342) ### Changed diff --git a/docs/adr/0013-ai-assisted-development-workflow.md b/docs/adr/0013-ai-assisted-development-workflow.md index 63a0894..4ff71f0 100644 --- a/docs/adr/0013-ai-assisted-development-workflow.md +++ b/docs/adr/0013-ai-assisted-development-workflow.md @@ -51,6 +51,7 @@ 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 @@ -60,6 +61,7 @@ independent of the primary workflow. than incidental ### Negative + - Token economics: long-running work may exceed context limits, requiring active session management and continuation prompts to resume work across sessions @@ -67,6 +69,7 @@ independent of the primary workflow. 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 diff --git a/docs/adr/0014-spec-driven-development.md b/docs/adr/0014-spec-driven-development.md index 1829d76..117d96e 100644 --- a/docs/adr/0014-spec-driven-development.md +++ b/docs/adr/0014-spec-driven-development.md @@ -38,6 +38,7 @@ 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 @@ -46,12 +47,14 @@ bumps) may skip the Issue step at the developer's discretion. 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;