first commit

2026-06-29 07:36:04 +02:00
commit 5e5b875e37
108 changed files with 13347 additions and 0 deletions
@@ -0,0 +1,76 @@
+# 0016. 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 ASP.NET Core 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