본문으로 건너뛰기

ADR-001: Document-Driven Backend Change Workflow

Status​

Accepted

Date​

2026-04-22

Context​

servers_v2 is already a multi-service system with:

  • split API and worker runtimes
  • legacy compatibility requirements
  • service-to-service contracts
  • health and rollout constraints
  • AI-assisted implementation and review

Chat history alone is not durable enough to preserve architecture intent. Large free-form reports also do not work well as execution inputs for AI workers.

We need a lightweight but enforceable documentation workflow that supports:

  • architecture stability
  • implementation execution
  • production rollout safety
  • AI-readable task handoff

Decision​

For backend changes with production impact, we will use a document-driven workflow.

Required document types:

  • stable docs under architecture/ and services/
  • ADR for durable architectural decisions
  • Spec for feature or migration requirements
  • Plan for executable implementation steps
  • Runbook for rollout and rollback operations

Minimum policy:

  1. Any service-boundary or ownership change must update or add an ADR.
  2. Stable system or service docs must be updated when platform truth changes.
  3. Any multi-service or compatibility-sensitive change must have a spec.
  4. Any non-trivial implementation must have a checklist-style plan.
  5. Any production rollout must have a runbook before cutover.
  6. Contract tests and health tests must be aligned with the spec before the change is considered complete.

Consequences​

Positive:

  • AI workers get durable execution inputs instead of relying on chat memory.
  • AI workers can separate stable system truth from dated change plans.
  • Compatibility constraints become explicit.
  • Rollout and rollback paths are defined before production changes.
  • Reviews can compare code against a stable spec instead of intent inferred from commits.

Negative:

  • Adds upfront documentation cost.
  • Requires discipline to keep docs updated alongside code.

Follow-Up​

  • Start using this workflow from the recon_service migration.
  • Keep documentation categories directly under docs/ for discoverability.
  • Maintain stable docs under docs/architecture/ and docs/services/.