Merge pull request #342 from nanotaboada/docs/adr-0013-0014

docs(adr): add AI workflow and SDD decision records

Author: nanotaboada

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 (#342)
+- ADR-0014: Adopt Spec-Driven Development (SDD) (#342)
 
 ### Changed
 

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

docs/adr/0013-ai-assisted-development-workflow.md

@@ -0,0 +1,76 @@
+# 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

docs/adr/0014-spec-driven-development.md

@@ -0,0 +1,61 @@
+# 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

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