Docs: decisions.md を per-file ADR 群へ移行（Phase 0-5 完了）#508
Open
Tomy-ch wants to merge 30 commits into
Open
Conversation
outbox-gc / idempotency-gc / usercount / relay が構造上並走安全である ことと、多重起動制御(concurrencyPolicy / advisory lock)はスケジューラ側 の決定である旨を out-of-scope に明文化。 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
decisions.md を MADR-lite の per-file ADR 群へ移行するための作業計画書。 リポジトリ全体スキャンで洗い出した対象約30件の採番案・粒度方針・フェーズ 別手順・参照貼り替え対象・リスク・完了条件を集約。移行完了後に削除する 一時文書として docs/design に配置。 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
✅ Secret scan: PASS (gitleaks)gitleaks log🔖 Commit: 🕒 UpdatedAt: 2026/07/06 00:45:20 (JST) |
採番を決定単位(約50本)へ細分化し、各 ADR に「作成時に再読すべきファイル」 と共通参照・再開手順を追記。会話コンテキストが失われても本ファイル単体で 各 ADR 作成を再開できるようにする。 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
DI で環境ごとに実装を差し替える決定(0018 env-gated wiring)を新規 ADR と して追加。0009 CQRS に CommandService(書き込み側)の存在を明記し参照を追補。 採番を通しで振り直し(約51本)、棄却した除外候補も明示。 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
初回スキャンで未カバーだった .github/scripts/docker/.claude/トップレベル 思想から 0052-0059 を追加: ロックイン回避原則 / IF-first 疎結合(DIP) / with-AI 方式(AGENTS.md) / docs 正典戦略 / Actions SHA ピン＋供給網検疫 / scripts は sh 不採用(Node,Go) / go:embed 自己完結バイナリ / docker-compose dev stack。約59本に更新。 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
cmd/build/CI/DB/openapi/env/test/開発方式を4系統で体系スイープし 0060-0084 を追加: CLI humble-object / 単一マルチコマンドバイナリ / 単一ランタイム イメージ+コマンド上書き / hardened-alpine / per-env イメージ / pre-deploy migration / cosign+SBOM 供給網 / deploy スケルトン / Make 単一入口 / カバレッジ90%gate+例外ガバナンス / CI 実 fx+実DB 起動検証 / 生成物ドリフト gate+自動生成bot / 多層セキュリティスキャン / merge-dml+dump-schema / master-vs-seed / DB内全文検索 / tag単位 oapi-codegen+strict-server / spec駆動 検証+認証 / 境界値オーナーシップ / Redocly bundle / envPrefix ローダ / default-vs-required / 実DB rollback テスト / 多モデル敵対レビュー / lean A scaffold。約84本に更新。保留候補8件も明記。 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
3rd pass の borderline を採用: GH Pages 公開 / 2層 golangci / mise SSOT 伝播＋ドリフトgate / lefthook が CI 契約複製 / system_query 第4カテゴリ / migration 連番採番規律 / metrics 認証例外 / 公式 semconv 使用(exclusion)。 約92本に更新。 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
発見順(1st/2nd/3rd/保留)の採番を、基礎原則→契約→HTTP→永続化→DI/config→ 非同期サブシステム→observability→ライブラリ/ビルド/CI→バイナリ/デプロイ→ 全体除外 の依存順へ並べ替え 0001-0092 に通し再採番。Phase を番号列挙から 種別ベース(migrate/★/new/exclusion)に変更し並べ替えに非依存化。 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
docs/design/adr/ に README(決定ログ+分類規約+supersede運用) / template.md (MADR-lite) / 0000-record-architecture-decisions(メタADR) / 見本 0001 (ロックイン回避) を追加。仮置きは docs/design/adr、最終配置は docs/adr。 計画書 Phase 0 の見本を 0001 に整合。 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
frontmatter に deciders を追加。Consequences を Benefits/Trade-offs から MADR 標準の Positive/Negative Consequences へ変更（0000/0001 も追随）。 mermaid を含む見本として 0002 onion を追加し、負の ADR も同一テンプレで 運用する方針を確定。 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
exclusion ADR に setup-review タグを付け、リポジトリセットアップ導線から 列挙して受容 or supersede させる方針を計画書に追加。ADR README/template に setup-review タグ規約を明記。 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
docs/get-started/setup-repository.md と ja 版に、setup-review タグ付き exclusion ADR をレビューし受容 or supersede する Phase 10 を追加(サンプル API 削除は Phase 11 に繰り下げ)。計画書の該当注記も追記済みへ更新。 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
セットアップは fork がテンプレの決定を自ベースラインとして引き取る一度きり の場なので、exclusion ADR は supersede でなく直接編集で書き換える方針に修正。 supersede は運用開始後の見直しに限定。setup-repository(en/ja) / ADR README / 計画書を整合。 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
decisions.md の技術選定根拠と、リポジトリ各所の潜在的アーキ決定を MADR-lite の per-file ADR(0001-0092)+メタ ADR(0000)として materialized。 依存/基礎度順に採番。exclusion(負の決定)は setup-review タグ付与。 README の決定ログを全 93 本に更新。配置は暫定 staging(docs/design/adr/)。 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
decisions.md にインラインだった直接依存表を、コード追従の「生きた目録」 として docs/reference/dependencies.md へ分離。旧表で欠落していた net/http/otelhttp 計装と otel/sdk/log SDK を補完。選定ポリシー(ADR-0064)と bridge 例外(ADR-0065)へ backlink。 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
decisions.md を per-file ADR 群(docs/design/adr/)と依存目録への リダイレクト stub 化。EN 正典(README/index/rules/design README/worker/ outbox/docs-structure)の decisions.md 参照を ADR 群・dependencies.md へ 貼替。outbox/worker は該当サブシステム ADR へ直リンク。 ※ ja ミラー・portal guides・AGENTS.md(人手)は Phase 5 テールで対応。 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Phase 0-4 完了(92本+メタを materialized、依存目録分離、decisions.md リダイレクト化、EN 正典参照貼替)と、残 Phase 5 テール(物理昇格・ ja ミラー・rules backlink・portal/AGENTS 参照)を先頭に明記。 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Tomy-ch
changed the title
暫定 staging だった docs/design/adr/ を最終配置 docs/adr/ へ git mv。 昇格に伴い全 ADR の相対リンクを機械的に書換（../../../→../../, ../../→../, ../→../design/）。移行計画書への被参照は ADR ログ(README.md)へ repoint し、README の provisional-staging 注記を撤去。 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
昇格に伴い EN 正典(README/index/rules/decisions redirect/design README/ docs-structure/dependencies)の ADR 参照を docs/adr/ へ更新。docs/rules.md の 主要ルール(層依存/生成コード/OpenAPI/migration/Repository・QueryService/ tx/error/toolchain 等)に対応 ADR への Rationale backlink を追加。 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
docs/adr/ の全 ADR を docs/ja/adr/ に日本語ミラー化。frontmatter は複製、 見出しを日本語化、英語正典へのバックリンクを付与。兄弟 ADR リンクは .ja.md、 その他相対リンクは深さ +1 で局所化。exclusion は setup-review タグ維持。 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
ja 正典(decisions.ja redirect/index/rules/design README/worker/outbox/ docs-structure)の decisions 参照を ADR 群へ更新。EN と対に docs/ja/reference/dependencies.ja.md を新規追加。 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
ADR 移行に伴い doc-reviewer エージェントの rationale 例示参照を更新。 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Tomy-ch
changed the title
ADR 移行(decisions.md → per-file ADR)に伴い、正典ドキュメント表の 技術選定根拠の参照先を docs/decisions.md(リダイレクト stub)から docs/adr/(ログ: docs/adr/README.md)へ更新。人手承認済みの編集。 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
ja ミラーが EN からドリフトしていた Phase 9 を同期。旧 ja は認証(JWT)の みで、authz(9.2)・fail-closed 前提・IMPORTANT 注記が欠落していた。EN の 「認証・認可の実装」(9.1 authn / 9.2 authz)全文を翻訳し反映。README リンクは .ja.md に局所化。見出し構造は EN と 1:1 に整合。 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
sonnet 検証者13体でコード/design doc/CI と照合し、裏取りできない記述を修正。 - ハルシネーション: 0003 randomness 境界(不在)→実在例に、0065 otelpgx の release-train 誤り訂正＋otelhttp を例外に追加。 - 数値/機構: 0016 middleware 優先度(logging 9・httpredmetrics 8 追加、rest.md も同期)、0056 graceful-stop 45s、0055 job は SupervisedRunner、0035 config は SetUpConfig/Load、0076 govulncheck は advisory(exit code でなく PR コメント)、 0068 .mk は明示 include 必要。 - 引用元/パス: 0001 policy.md、0078 infra 85%出典、0081 cli/outbox、0082 db-seed、 0025 <aggregate>_repository.go、0010 gen-api、0059/0070/0072/0077/0089。 検証で74/93はOK。 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Tomy-ch
commented
Jul 4, 2026
Tomy-ch
commented
Jul 5, 2026
Tomy-ch
commented
Jul 5, 2026
Tomy-ch
commented
Jul 5, 2026
作者が ja 版 ADR に残したレビューコメントのうち妥当なものを、canonical=EN と ja ミラー両方へ反映。主に根拠(Why)の追記・ネガティブ影響の再フレーム・冗長な サンプル例の削除・誤読を招く記述の訂正。 - 追記: 0002 Fat Model回避 / 0003 IF契約の保守性 / 0007 出力収束・想定所有 / 0008 英語正典の AI トークン理由 / 0009 契約先行レビュー / 0010 YAML先行 / 0011 コンフリクト・行数 / 0012 契約最優先 / 0019 SQL共通言語・ORM追従リスク / 0021 ローカルDB前提・schema スナップショット / 0030 手動DI却下理由 / 0039 複数アダプタ回避 / 0058 export 強制意図 / 0068 単一実装呼出 / 0069 shell不適 / 0014 BasicAuth 多層防御・Authn却下。 - 再フレーム(ネガ→意図/中立): 0037 ErrInternal / 0067 drift gate ガードレール / 0009 生成手順の隠蔽。 - 削除/訂正: 0024 サンプル固有の例・seed 説明 / 0033 config 詳細を README 参照へ。 EN と ja を同期。 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
作者レビューを受け、システム運用クエリ(health/idempotency/outbox)の DML カテゴリと infra 実装を system_query→system_cqrs へ改名（読み書き両方を 含むため cqrs が適切）。コード(dir/型 DBSystemQuery→DBSystemCqrs/fx module/ import)・DML・merge type・生成物(sqlc/mock 再生成)・READMEs・design docs・ ADR テキストを一括更新。make gen-query 再生成、build/lint/test/sql-lint 全通過。 あわせて 0025 に CommandService(コマンド/書込パス)を作者方針で明記 （実装は予約 placeholder の旨を注記）・Repository を集約 CRUD+一部集計に是正・ QueryService 最適化やドメイン貧血アンチパターンを明確化。0026 の repository 1:1 根拠を補強。EN と ja を同期。 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
- 0000: 分離に至る固有の歴史的背景(OBSERVABILITY_ENABLED 例等)を除去。fork 先で ノイズになるため一般原則のみ残す。 - 0002: ドメイン＋usecase を「移植可能なコア」とする移植性の根拠を追記 (Go 内なら 2 層の引っ越し、別言語でも 2 層の解析に帰着)。 - 0013: エラー値がレイヤーごとに異なる旨・所有者分離(DBA/開発者/ドメインエキスパート)の ポジティブ性を追記(包含方向は正しいため据え置き)。 - env/.env.prd: メトリクス BasicAuth 資格情報を除去しデプロイ時 env 注入に変更。 - doc-reviewer: ディレクトリ参照時はまず README を読む指針を追記。 EN と ja を同期。 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
作者レビューに基づく構成変更: - 新規 0014「検証の権威はドメイン」を境界値所有権の前段に追加し、旧 0013 (spec-driven-validation)→0013、境界値所有権→0015 に。0015 から 0014 を参照。 - 新規 0012「生成 openapi.gen.yaml をフロント型生成用に保持」を契約セクションに追加。 - 旧 0028「DB内全文検索」を削除(作者方針: サンプルであり本来は専用エンジン)。 - 上記の挿入/削除に伴い旧 0012-0092 を依存順に再採番(0013/0015-0093)、0026 の slug も system-cqrs-dml-category へ。全 ADR/rules/dependencies/design/decisions の 相互参照(ADR-NNNN・ファイル名)を一括更新、README ログ(EN/ja)を全94本で再生成。 - design docs の adr 相対リンク深さ(../adr/)を是正。 検証: 見出し==ファイル名・ja backlink 整合・全リンク解決・宙ぶらり参照ゼロ・md-lint green。 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
✅ Trivy FS: PASS (no vulnerabilities)📄 Summary🔖 Commit: 🕒 UpdatedAt: 2026/07/06 00:44:23 (JST) |
✅ govulncheck: PASS (no actionable vulnerabilities)📄 Summary🔖 Commit: 🕒 UpdatedAt: 2026/07/06 00:44:40 (JST) |
✅ SQL lint: PASS
✅ migrations log✅ dml log✅ seed log🔖 Commit: 🕒 UpdatedAt: 2026/07/06 00:44:56 (JST) |
✅ No differences in OpenAPI generated output were detectedNo differences in OpenAPI generated output were detected. 🔖 Commit: 🕒 UpdatedAt: 2026/07/06 00:45:06 (JST) |
✅ No differences in database output were detectedNo differences in database output were found. 🔖 Commit: 🕒 UpdatedAt: 2026/07/06 00:45:24 (JST) |
✅ Go lint: PASS (golangci-lint)golangci-lint log🔖 Commit: 🕒 UpdatedAt: 2026/07/06 00:45:37 (JST) |
✅ No differences in Go generated output were detectedNo differences in Go generated output were detected. 🔖 Commit: 🕒 UpdatedAt: 2026/07/06 00:45:54 (JST) |
This comment has been minimized.
This comment has been minimized.
docs/adr/ を portal の auto-discovered セクションとして閲覧可能にする。curated guide(reading list カード)には登録せず、manifest の構造制御のみ追加: - meta.groups に "Decisions (ADR)" グループ(section: adr)を追加。 - meta.subgroups.adr で 94本を番号(依存)順の論理区分に整理(Index/Meta・基礎・契約・ HTTP・永続化・DI/config・非同期・o11y・ライブラリ・toolchain・CI・プロセス・ バイナリ/デプロイ・除外)。README=決定ログ索引。 - section_titles に adr / reference を追加し、依存目録 reference も Architecture へ配置 (Uncategorized 化を解消)。 docs.json は make gen-docs-json で再生成。SPA は docs/adr/ の生 md を直接レンダリング (guides へのコピーは不要)。全192 item(EN/JA)のパス解決を確認。 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Code Metrics Report
Details | | #301 (51952c3) | #508 (a6f5dcf) | +/- |
|---------------------|----------------|----------------|--------|
+ | Coverage | 98.4% | 99.4% | +1.0% |
| Files | 152 | 257 | +105 |
| Lines | 2282 | 4626 | +2344 |
+ | Covered | 2247 | 4602 | +2355 |
+ | Code to Test Ratio | 1:1.6 | 1:2.2 | +0.5 |
| Code | 9106 | 14296 | +5190 |
+ | Test | 14695 | 31471 | +16776 |
- | Test Execution Time | 24s | 50s | +26s |Code coverage of files in pull request scope (95.2% → 99.2%)Skip file coverages because there are too many files (149) Reported by octocov |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
概要
docs/decisions.md（約8決定＋依存表を1ファイルに集約）を MADR-lite の per-file ADR 群へ移行する作業です。fork 利用者がモノリスを触らず1ファイル追加で個別 supersede できるようにすることが目的です。Phase 0–5 まで完了しました（型固定 → 全92決定＋メタの materialize → 依存インベントリ分離 → decisions.md リダイレクト化 → 参照貼替 →docs/adr/への昇格 → 日本語ミラー → 移行計画書の削除）。変更内容
ドキュメントのみの変更です（実装コードの変更はありません）。
docs/adr/0000（メタ）〜0092。依存/基礎度順に採番。migrate 11本＋new＋exclusion。exclusion（負の決定）はsetup-reviewタグ付与。docs/adr/README.mdに決定ログ（全93本）。docs/design/adr/を最終配置docs/adr/へ移動し、全 ADR の相対リンクを整理。docs/reference/dependencies.md（EN）/docs/ja/reference/dependencies.ja.md（ja）へ分離。欠落していたnet/http/otelhttp・otel/sdk/logを補完。docs/decisions.md/docs/ja/decisions.ja.mdを stub 化。EN/ja 正典（README/index/rules/design/worker/outbox/docs-structure）＋AGENTS.mdの参照を ADR 群へ更新。docs/ja/adr/に全93本＋README/template を作成（frontmatter 複製・見出し日本語化・英語正典バックリンク）。docs/design/adr-migration-plan.mdを削除し、被参照を ADR ログへ repoint。動作確認方法
ドキュメントのみのため実行時の動作確認は不要です。
make md-lint— markdownlint + mermaid-lint がグリーン（0 error）setup-reviewタグ・見出し採番の整合を確認済み（相対リンク解決はプレースホルダXXXX-....mdを除き全解決）grep -rl "setup-review" docs/adr/で exclusion ADR を列挙可能（setup-repository Phase 10 導線が機能）make lint/test-cached/sql-lint/ actions-lint / docker-lint / pin-actions-check / migration-check も OK（Go/SQL/CI 無変更）補足
AGENTS.mdの技術選定根拠参照もdocs/adr/へ更新済み（人手承認のうえ編集）。docs/ja/get-started/setup-repository.ja.mdの EN ドリフト（Phase 9 の authz/fail-closed 欠落）も同期済みです。docs/portal/guides/**は生成物のため本 PR では未編集（再生成で追従）。