■ 1. 対象システムと背景
- アンシンアプリ:
- 人員、予定、実績、請求から成果の集計、分析までを一貫管理する経営支援システム
- 勤怠管理、給与計算、サービス提供計画、チームチャット、一般請求管理を備える
- 医療、介護請求（国保連請求）、集計、分析、プロジェクト管理、お客様マイページも備える
- リポジトリの増殖:
- 2021年頃はフロントエンド、バックエンド、インフラの3リポジトリで開発を開始
- 現在は2つのモノレポを含む13リポジトリでシステム本体を構成
- 全社戦略と補助サービスの2リポジトリを加え、ドキュメント管理対象は15リポジトリ、25ドキュメントルート
- スマホアプリ、広報サイト、脆弱性チェック、マーケティング管理まで需要に応じてリポジトリが増加
■ 2. 正本喪失による負のスパイラル
- 無秩序なドキュメント配置:
- 配置や管理のルールが未整備で、仕様書や運用資料が各リポジトリのdocuments/配下へ秩序なく蓄積
- 似た内容の文書が複数存在し、どれが現行仕様の正本か判断できない状態が発生
- AI駆動開発での誤動作:
- 正本が定まらない環境では、AIが古いMarkdownを現行仕様と認識し誤った前提から実装を作成
- 当時使用していた高性能なAIモデルも人間と同様に迷った
- 負のスパイラル:
- 依頼前にソースコードから仕様を復元させ、人間が確認してから改修する手順が毎回必要
- そのたびに新しいMarkdownが増え、文書がさらに膨張
- 本質的な課題:
- 問題は文書の量ではなく、必要な情報を機械的に判定できないこと
- 現行仕様の正本か、参考資料や作業記録かを判定できない
- 管理責任者、確認日、確認者を判定できない
- 対応するコード、API、DB契約、テストを判定できない
- 統合すべきか別責務として残すべきかを判定できない
- 変更中か、削除、移動してよい文書かを判定できない
- 分離されていなかった概念:
- 「文書が存在すること」と「現行仕様を説明する正本であること」が未分離
- AIへ依頼するたび、人間がソースコードと文書のどちらが正しいか確認し直す必要が発生
- AIによる高速化の前に、AIが参照する情報環境そのものの整備が必要
■ 3. 設計方針と判断の契約
- 機械検証可能な管理基盤:
- 単なるフォルダ整理ではなく、人間とAIが同じ根拠を参照できる基盤を構築
- 「どれが正本か」「実装と一致しているか」「次に何を確認すべきか」を判断可能にする
- AIと人間の責務分割:
- AIに全ファイルを読ませて自由に移動、削除させることはしない
- 最初にAIが判断できる範囲と人間が判断すべき範囲を契約として分離
- AIが担う処理:
- 全ドキュメントルートの走査とinventory生成
- frontmatter、manifest、リンクの検証
- hash、Git履歴、参照関係、本文類似度の比較
- 正規配置先、統合候補、削除候補の提示
- 台帳、review queue、管理画面用bundleの再生成
- build checkとworktree監査による再発検知
- 人間が担う判断:
- 業務上の正本、承認者、例外処理の確定
- 法務、認証、認可、課金など高リスク仕様の承認
- 意味が競合する文書の採用、統合、廃止判断
- 移動、削除、commit、releaseの実行許可
- 公開情報や対外表現の最終確認
- AIの根拠が不足する場合の追加情報提供
- AIを承認者にしない:
- AI自身をレビュー担当者や承認者として記録することを禁止
- AIは証拠収集、矛盾検出、候補提示は可能だが、組織として何を正本にするかの責任は代替不能
■ 4. AIが反復できる整備フロー
- 再実行可能な手順:
- 一度きりの手作業ではなく、AIが同じ手順を再実行できる流れとして設計
- フローの各段階:
- 全リポジトリ、全ドキュメントルートを走査し、所在とSHA-256をinventoryへ固定
- 用途をspec / decision / runbook / plan / status / evidence / reference / template / generatedへ分類
- domain、コード、テスト、API、DB契約、Git履歴、他文書からの参照を照合
- 正規配置先、統合候補、削除候補、判断に必要な不足情報を生成
- 根拠が一意なものは同じdoc_idを維持して移動、統合し、曖昧なものは人間の確認対象として停止
- manifest、canonical index、inventory、review bundleを決定的に再生成
- 各リポジトリの./scripts/build_check.shで配置、メタデータ、重複、リンク、生成物の差異を検査
- 作業用worktreeがMainへ取り込まれたら差分を監査、保全のうえ撤去し、古い作業コピーを残さない
- 途中状態を複製しない原則:
- 承認待ち文書を別のpending/フォルダへコピーせず、移行前の配置を唯一の原本として維持
- 承認後にだけ正規パスへ移動し、AIが二つの正本候補を見つける問題を回避
- 初回移行は完了済みで、正規配置上のGit管理文書がそのまま正本
■ 5. 正本を機械可読にする仕組み
- 正規配置:
- 配置は文書の用途とdomainから決定
- documents/配下にREADME.md、manifest.yamlを置く
- specs、decisions、runbooks、plans、status、evidence、references、templates、generatedを
単位で配置 - doc_idによる同一性:
- 各Markdownに安定したdoc_id、管理責任者、正本性、状態、参照元、コード、契約、テストとの対応を付与
- ファイルを移動してもdoc_idは不変
- リポジトリをまたぐ参照もパスではなくdoc_idで解決
- frontmatterは契約:
- 本文の前に置くfrontmatterは単なる検索用タグではない
- 文書の配置先、管理者、AIが参照できる根拠の種別を定める契約として機能
- frontmatterの各項目:
- schema_version / doc_idはメタデータ形式と、移動しても変わらない文書IDを定義
- domain / document_kind / scopeは文書の責務と正規配置を決定
- status / plan_stateは文書の確認段階と計画の進行状態を分離
- owner / authorityは管理責任者と、正本、参考、生成物などの役割を提示
- source_doc_ids / consumersは参照元と利用先をpathではなくIDで接続
- code_paths / contract_paths / test_pathsは実装、API、DB契約、テストとの対応を追跡
- last_reviewed / review_interval_daysは確認日と再確認期限を提示
- sensitivityは管理画面や生成bundleで本文を扱えるかを制御
- statusとplan_stateの分離:
- statusは文書としての確認段階、plan_stateは提案中、承認済み、進行中、完了のいずれかを表現
- AIが両者を混同し、提案段階の計画を実装済み仕様として扱うことを防止
- 正本と派生物の区別:
- 正本は各Markdownのfrontmatterと各ドキュメントルートのmanifest
- canonical index、inventory、review queue、管理画面用bundleは再生成可能な派生物
- 生成物を手で直して一時的に整合させることは不可能
- 重複判定:
- ファイル名だけでは判定せず、完全一致のhashに加え、topic、本文類似度、参照関係を確認
- Git上の更新履歴と生成元の責務も確認
- 見た目が似ていても別アプリが独立生成する契約なら、統合しない理由と両方のhashを記録
- 本文が変われば判断はstaleとなり再確認が必要
■ 6. 品質ゲートとしてのbuild check
- ローカル入口への組み込み:
- ルールを文書に書くだけでは次の作業で忘れられる
- 管理対象15リポジトリすべての./scripts/build_check.shへドキュメント規定の検査を組み込み
- 中央と各リポジトリの役割:
- 中央にポリシー、schema、registry、checkerを配置
- 各リポジトリへはバージョンとハッシュで固定した可搬な検査契約を配布
- 単独cloneではそのリポジトリのドキュメントルートを検査
- Anshinのworkspaceでは登録済み25ルートすべてを検査
- build checkを失敗させる状態:
- frontmatterや必須メタデータの欠落
- 重複したdoc_id、正規配置外の文書、仮分類の再混入
- manifestとcanonical indexの不一致
- 壊れたリンク、端末固有path、secretや管理対象外artifactの混入
- 未判断の完全重複、高類似文書
- 実装変更に必要なcanonical specやchange contractの不足
- checkerや配布した検査契約自体のハッシュ差異
- lease切れ、Main取り込み後も残った作業worktree
- CIを正本にしない:
- GitHub Actionsからもbuild checkを呼び出せるが、品質判断の正本はCIではない
- AI、人間、commit前検査、release runnerが同じローカル入口を使用
- 「CIでは通るが手元では規定を迂回できる」という分岐を作らない設計
■ 7. 採用したベストプラクティス
- 組み合わせによる設計:
- 特定フレームワークをそのまま導入したものではない
- 技術文書、ソフトウェア設計、構成管理、セキュリティで実績のある考え方を組み合わせて適用
- Docs as Code:
- 文書もコードと同様にplain text、Git、code review、自動テストで扱う考え方
- Markdown、manifest、schema、checkerをリポジトリで管理し、実装と同じbuild_check.shで検査
- Diátaxis:
- 読み手の目的に応じてtutorial、how-to、reference、explanationを分離する考え方
- 仕様、判断、運用、証跡、参考資料、生成物を混在させず、document_kindとdomainで責務を分離
- 一対一のfolder対応にはせず、開発、運用責務に合わせて分類を拡張
- Architecture Decision Records:
- 重要な設計判断を背景、判断、結果を持つ小さな記録として残す考え方
- decisions/
/を独立させ、採用理由と代替案を将来のAIと人間が追跡可能にする - GitOps Principles:
- 期待状態を宣言的かつversion管理し、実状態との差を継続的にreconcileする考え方
- frontmatterとmanifestを期待状態、inventoryとcheckerを観測、照合手段として使用
- Adminやrunnerからは自動でGitを更新せず、実行権限を別に保持
- 文書を無条件に自動移動せず、根拠が揃った変更だけを人間が承認する設計
- 自動化するのは観測、比較、検証であり、曖昧な業務判断は自動化しない
- JSON Schema:
- 機械可読データの構造、型、必須項目をschemaで検証する考え方
- メタデータ、manifest、レビュー判断、統合証跡を実際のschemaで検証
- schemaを読み込むだけの見かけ上の検査を禁止
- 楽観的排他制御:
- 更新前のrevisionが変わっていたら書込みを拒否し、lost updateを防ぐ考え方
- document SHA-256、inventory SHA-256、編集前blob IDを照合
- 一件でもstaleなら移動、一括判断、integrationを停止
- 再現可能な生成:
- 同じ入力と手順から同じ成果物を再生成し、差異を独立に検証する考え方
- canonical index、inventory、review queue、bundleを決定的に生成
- 手編集や生成時刻、順序による不要な差異を排除
- Least PrivilegeとSeparation of Duties:
- 必要最小限の権限だけを与え、判断と実行の責務を分離する考え方
- AIの候補提示、人間のreview、runnerによる移動、commit、push、releaseを別権限に分離
- Admin APIにはGit書込み権限を付与しない
- 概念を混同しない重要性:
- Gitを正本にすることは「Gitにある全ファイルが現行仕様」を意味しない
- Docs as Codeだけでは正本性を表現できないため、authorityとstatusをメタデータで分離
- 特定標準への準拠や認証取得を主張するものではなく、必要な部分だけを機械検証可能なcontractへ落とし込んだもの
■ 8. 926件を判断可能にする管理画面
- 棚卸しの規模:
- 15リポジトリ、25のドキュメントルートから926件の文書、生成物を検出
- 926件をJSONへまとめただけでは人間が判断できる管理にはならない
- 一件ずつファイルを開いて正本か計画中か参考資料かを判断するのは非現実的
- Admin管理画面:
- AIが収集、分類した結果を人間が判断できる形へ変換するためAdminに実装
- 正本、計画中、要確認、資料、生成物、履歴の5分類で確認可能
- リポジトリや状態で絞り込み、選択した文書の本文とGit差分をGitHubのように右側で確認
- 人間は926件すべてを読まず、AIが絞り込んだ判断が必要な文書に集中可能
- Adminを正本にしない:
- 正本は各リポジトリでGit管理されたMarkdown本文、frontmatter、配置
- Adminはそこから決定的に生成されたinventoryとprivate bundleを表示する読み取り専用カタログ
- DBを現在状態の管理から外した理由:
- 初回移行では「正本として移行」「削除対象」「要修正」「保留」の判断機能を使用
- 移行完了後までDBで文書状態を管理すると、GitとDBのどちらが正しいかという新問題が発生
- 通常運用ではDBを現在状態の管理から除外し、初回移行時の判断履歴だけを監査証跡として保持
- 新しい文書や更新された文書をDBへ登録する必要はない
- 誤操作の遮断:
- Adminからファイルの移動、削除、commit、pushは実行不可
- AIによる分類、人間による判断、Git変更、検証、公開を分離
- 管理画面の誤操作がそのまま文書破壊につながらない設計
■ 9. 仕様書化の線引き
- 過剰な文書化の弊害:
- あらゆる実装に長い仕様書を要求すると、文書の更新自体が目的化する
- すぐに実装との差異が発生する
- コードを根拠にする範囲:
- 局所的で、コードの型、名前、コメント、テストから振る舞いが一意に分かる変更はそれらを根拠とする
- 正本仕様を作る範囲:
- 複数リポジトリに影響する変更
- 大規模な仕様変更
- API、DB契約、運用、ロールバック
- 将来の判断に理由を残す必要がある場合
- 新規開発時の手順:
- AIはまずregistryとcanonical indexから関連文書を特定
- 次に対応するコード、契約、テストを確認
- 文書が不要な変更では無理に増やさず、必要な場合は実装と同じ変更単位で更新
- 「文書を読めば分かる」と「コードを見れば分かる」の双方で根拠を追跡可能にする
■ 10. 成果
- 最大の変化:
- 成果はフォルダがきれいになったことではない
- AIへ機能改善を依頼するたびにソースコードから仕様を起こし直す必要がなくなった
- 整備前のフロー:
- 機能改善を依頼するとAIが古い文書を参照し、誤った前提や実装が発生
- 人間がソースコードから仕様を再確認し、新しい説明文書を作成して文書がさらに増加
- 整備後のフロー:
- AIが正本と実装根拠を特定し、既存仕様を踏まえて設計、実装
- 必要な文書だけを実装と同時に更新し、build_check.shが不整合を検出
- 整備された情報が次の開発の根拠として蓄積
- 2026年8月17日時点の数値:
- 管理対象リポジトリ15、ドキュメントルート25、inventory登録件数926、canonical文書62
- 正本37、計画中50、要確認18、資料、生成物786、履歴35
- 検査エラー0、検査警告0、未解決の重複0
- 迂回不能な検査:
- 全リポジトリの./scripts/build_check.shに共通のドキュメント検査を組み込み
- 規定外配置、メタデータ不足、壊れたリンク、生成物の差分、重複文書、放置worktreeで通常のbuild checkが失敗
- 検査をCIだけに置かず、AIも人間も同じローカル入口を使うことで規定の迂回を防止
- 未承認領域の明示:
- 926件すべてを内容まで承認済みとはしていない
- AIは配置、hash、Git履歴、参照関係、コードやテストとの対応は検査可能
- 事業方針、法務判断、高リスクな認証仕様をAIが勝手に承認することは不可
- 人間の確認が必要な文書は明示的に要確認として保持
- 曖昧な文書を無理に正本化せず、機械的確認と人間の判断を分離できたことも重要な成果
■ 11. まとめ
- AI駆動のドキュメント整備の本質:
- AIに文章を書かせることではない
- 得られた要点:
- Git管理されたMarkdown、frontmatter、配置を文書の正本にする
- AIは走査、比較、矛盾検出を担い、正本や高リスク仕様の承認は人間が担う
- 決めた規定を各リポジトリの./scripts/build_check.shで継続的に検証する
- 情報環境の設計が要:
- 曖昧な情報環境では、AIは誤りも速く増幅する
- 正本、責務、判断境界、検査方法が明確であれば、AIは文書を整え次の開発へ知識を引き継ぐ存在になる
- 重要なのはAIの導入自体ではなく、AIが安全に力を発揮できる情報環境の設計
- 構築した仕組みを今後の機能追加や仕様変更とともに継続的に育てる