最終更新: 2026/06/22 18:56
commonid: rq-095-drp-layered-docs-architecture-p…type: promptstatus: active

Research Question

What documentation architecture best supports layered requirements-to-design documents (business requirements, system requirements, external design, internal design) with lightweight change-impact traceability, for a solo-developer docs-as-code project?

[Scope: document structure, layering standards, and traceability schemes maintainable in Markdown + Git. NOT documentation-site tooling (static site generators), NOT requirements-elicitation process/workshops, NOT heavyweight ALM/RM tools (DOORS, Jama).]

Context

We operate a Decision Review Pipeline: an LLM-based review system for Architecture Decision Records, running on Cloudflare Workers (Queues, Durable Objects, D1) + LiteLLM Gateway, with gates Triage → Blind-spot Detection → Body Generation → Scoring → Cross-Validation → Consistency → Parallel Review → automated PR creation. Solo developer; all docs are Markdown in Git, published as a static site; primary language Japanese.

Current state:

  • A single 750-line README is the only system overview (purpose, design principles, architecture diagrams, gate table, phase history, ops info).
  • Per-node design docs, prompt design docs, an operator guide, and 110+ ADRs exist, but no explicit requirements layer: business requirements, system requirements, and external/internal design are mixed into the README and scattered ADRs.
  • Change impact is judged ad hoc: we cannot systematically tell whether a proposed change alters business requirements, system requirements, or only internal design.
  • Design artifacts (data definitions/schemas, API endpoint specs, prompt specs, state machines) are not separated into dedicated documents.

Gap: we need a page structure that separates requirement/design layers, an ID and traceability scheme linking them, and an operational method to classify each change's impact level before implementation.

Questions

  1. Layering standard: Which documentation layering models best fit a solo-developer docs-as-code repo — e.g. ISO/IEC/IEEE 29148 artifact set, V-model deliverables, Japanese frameworks (RDRA 2.0, IPA's 要件定義/外部設計/内部設計 deliverable conventions), or an arc42 + ADR hybrid? Compare 2-3 candidates with concrete artifact lists, and state the selection criteria (maintenance cost, layer-boundary clarity, JP-practice alignment).
  2. Traceability without heavy tooling: What ID schemes and traceability-matrix practices keep business-requirement ↔ system-requirement ↔ design ↔ implementation links maintainable in plain Markdown + Git? Include evidence on maintenance cost, known failure modes (stale links, matrix rot), and automation patterns (lint/CI link checks, generated matrix views).
  3. Design-artifact decomposition: For an LLM pipeline product, what is the standard set of separated design documents (data definition/schema doc, API spec e.g. OpenAPI, prompt spec, state-machine spec, non-functional spec), and where exactly is the boundary between external design (externally observable contracts) and internal design (implementation choices)?
  4. ADR integration and impact classification: How should ADRs coexist with layered requirements docs — which decision types belong in which layer, and how is duplication avoided (SSoT rules, pointers)? What practical frameworks classify a change's impact level (business-requirement change vs system-requirement change vs design-only change), and how are they operationalized as a pre-change checklist?
  5. Incremental migration: What are proven practices for retrofitting a layered structure onto one large existing overview doc — extraction order, SSoT rules preventing drift between the new layers and the old page, and a measurable definition of done for the migration?

Output

Structured report with:

  • Executive summary (3-5 key findings + decisive recommendations)
  • Per-question analysis with concrete, measurable answers
  • Decision matrix for Question 1 (rows = candidate architectures, columns = the selection criteria)
  • A concrete recommended page tree (artifact names + 1-line purpose each) for this pipeline
  • Priority ranking: must-have / should-have / nice-to-have
  • References with URLs (standards and official sources preferred)