AIが迷わない開発環境を、AIとつくる——リポジトリ横断ドキュメント管理の再設計

はじめまして。アシアルの松本です。

今回は、私が運営するシステムで進めたドキュメント管理の抜本的な再設計について紹介します。複数のリポジトリに分散し、正本が分からなくなっていた文書を、AIと人間が同じ根拠から判断できる管理基盤へ移行するまでの技術的な取り組みです。

対象となった「アンシンアプリ」

今回ドキュメントを整備したのは、人員・予定・実績・請求から、成果の集計・分析までを一貫して管理する経営支援システムです。

このシステムはアンシンアプリと呼んでいます。

現在は、「勤怠管理」「給与計算」「サービス提供計画」「チームチャット」「一般請求管理」「医療・介護請求（国保連請求）」「集計・分析」「プロジェクト管理」「お客様マイページ」など、事業所運営に関わるさまざまな機能を備えています。

アンシンアプリの主な機能例。訪問スケジュールと勤怠管理に特化したスマホアプリ、お客様マイページ専用スマホアプリ、顔認証による勤怠記録スマホアプリ、広報サイトに加え、脆弱性チェックやマーケティング管理を行うシステムまで、需要に合わせてリポジトリが増えていきました。

13リポジトリへ広がり、正本が分からなくなった

アンシンアプリの開発は2021年頃に始まりました。当初はフロントエンド、バックエンド、インフラの3リポジトリでしたが、現在は2つのモノレポを含む13リポジトリで構成されています。

なお、後述するドキュメント管理では、全社戦略と補助サービスの2リポジトリも対象に加えています。そのため、システム本体は13リポジトリ、ドキュメント管理の対象は15リポジトリ・25ドキュメントルートです。

一方、ドキュメントの配置や管理に関するルールは十分に整備されておらず、仕様書や運用資料が各リポジトリのdocuments/配下へ秩序なく置かれていました。その結果、似た内容の文書が複数存在し、どれが現在の仕様を示す正本なのか、判断できない状態になっていました。

正本が定まっていない環境でAI駆動開発を進めると、古いMarkdownを現行仕様として認識し、誤った前提から、もっともらしい回答や実装を作ってしまう状態になっていました。

人間だけでなく、当時使用していた高性能なAIモデルも同じように迷いました。機能追加や改善を依頼する前に、まずソースコードから仕様を復元させ、人間が内容を確認してから改修を進める。そのたびに新しいMarkdownが増えるという、負のスパイラルに陥っていました。

正本が不明な状態では、古い文書の参照、誤実装、人による再確認と仕様の再作成が繰り返されます。

問題を整理すると、文書の量そのものではなく、次の情報を機械的に判定できないことでした。

その文書は現行仕様の正本なのか、参考資料や作業記録なのか
管理責任者は誰か、いつ、誰が内容を確認したのか
どのコード、API・DB契約、テストと対応しているのか
同じ話題の文書と統合すべきか、別の責務として残すべきか
変更中の文書なのか、削除・移動してよい文書なのか

つまり、「文書が存在すること」と「現行仕様を説明する正本であること」が分離されておらず、AIへ作業を依頼するたびに、人間がソースコードと文書のどちらが正しいかを確認し直さなければなりません。AIによる高速化の前に、AIが参照する情報環境そのものを整える必要がありました。

図1：各リポジトリで正規配置への移行を始める直前のGit履歴から、実際のフォルダ名とファイル名を復元した構成図。Gitで管理されていなかったファイルは含まない。

AIが迷わないドキュメント管理を設計する

そこで、単なるフォルダ整理ではなく、人間とAIが同じ根拠を参照し、「どれが正本か」「実装と一致しているか」「次に何を確認すべきか」を判断できる、機械検証可能なドキュメント管理基盤を構築することにしました。

本稿では、複数のサービスとリポジトリに分散していた文書を、AI駆動で棚卸し・分類・統合・検証し、その整備された状態を継続的に維持できる仕組みへ変えた過程を紹介します。

AIに整理を任せる前に、判断の契約をつくる

AI駆動で整理するといっても、AIに全ファイルを読ませて、自由に移動や削除をさせたわけではありません。最初に行ったのは、AIが判断できる範囲と、人間が判断しなければならない範囲を契約として分けることでした。

AIが担う処理	人間が担う判断
全ドキュメントルートの走査とinventory生成	業務上の正本、承認者、例外処理の確定
frontmatter、manifest、リンクの検証	法務、認証・認可、課金など高リスク仕様の承認
hash、Git履歴、参照関係、本文類似度の比較	意味が競合する文書の採用・統合・廃止判断
正規配置先、統合候補、削除候補の提示	移動・削除・commit・releaseの実行許可
台帳、review queue、管理画面用bundleの再生成	公開情報や対外表現の最終確認
build checkとworktree監査による再発検知	AIの根拠が不足する場合の追加情報提供

AI自身をレビュー担当者や承認者として記録することも禁止しました。AIは証拠を集め、矛盾を検出し、候補を提示できます。しかし、組織として何を正本にするかという責任まで代替するものではありません。

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管理文書がそのまま正本です。

正本を機械が読める形にする

正規配置は文書の用途とdomainから決まります。

documents/
├── README.md
├── manifest.yaml
├── specs/<domain>/
├── decisions/<domain>/
├── runbooks/<domain>/
├── plans/<domain>/
├── status/<domain>/
├── evidence/<domain>/
├── references/<domain>/
├── templates/<domain>/
└── generated/<domain>/

各Markdownには、安定したdoc_id、管理責任者、正本性、状態、参照元、コード・契約・テストとの対応などをメタデータとして持たせました。ファイルを移動してもdoc_idは変えません。リポジトリをまたぐ参照も、パスではなくdoc_idで解決します。

Markdownの先頭を、AIと人間の共通契約にする

実際のMarkdownでは、本文の前に次のようなfrontmatterを置きます。以下は公開用に値を置き換えた例です。

---
schema_version: 2
doc_id: example.product.feature-plan
title: "新機能 設計計画"
domain: "feature-example"
document_kind: plan
plan_state: proposed
scope: product
product: "example-product"
owner: "product-team"
authority: reference
status: draft
risk_level: normal
source_doc_ids: []
consumers: []
code_paths: []
contract_paths: []
test_paths: []
last_reviewed: null
review_interval_days: 90
sensitivity: internal
---

# 新機能 設計計画

## 目的

このfrontmatterは、単なる検索用タグではありません。文書をどこへ配置し、誰が管理し、AIがどのような根拠として参照できるかを定める契約です。

項目	役割
`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だけでは進捗を表しません。statusは文書としての確認段階、plan_stateは計画が提案中・承認済み・進行中・完了のどこにあるかを表します。AIが両者を混同して、提案段階の計画を実装済み仕様として扱うことを防ぎます。

このfrontmatterをschemaで検証し、manifest、canonical index、inventory、Admin画面へ同じ値を流すことで、人間とAIが別々の基準で文書を解釈しないようにしています。

正本は各Markdownのfrontmatterと各ドキュメントルートのmanifestです。canonical index、inventory、review queue、管理画面用bundleは、そこから再生成できる派生物にしました。生成物を手で直して一時的に整合させることはできません。

重複判定もファイル名だけでは行いません。完全一致のhashに加え、topic、本文類似度、参照関係、Git上の更新履歴、生成元の責務を確認します。見た目が似ていても別アプリが独立して生成する契約なら、統合しない理由と両方のhashを記録します。本文が変われば、その判断はstaleになり再確認が必要です。

品質ゲートの正本はCIではなく、各リポジトリの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

GitHub Actionsからもこのbuild checkを呼び出せますが、品質判断の正本はCIではありません。AI、人間、commit前検査、release runnerが同じローカル入口を使うことで、「CIでは通るが、手元では規定を迂回できる」という分岐を作らない設計にしました。

採用したベストプラクティス

今回の設計は、特定のフレームワークをそのまま導入したものではありません。技術文書、ソフトウェア設計、構成管理、セキュリティで実績のある考え方を組み合わせ、複数リポジトリをAIと人間が共同管理する環境へ適用しました。

ベストプラクティス	一般的な考え方	今回の適用
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`で責務を分ける
Architecture Decision Records	重要な設計判断を、背景・判断・結果を持つ小さな記録として残す	`decisions/<domain>/`を独立させ、現在の仕様だけでなく、採用理由と代替案を将来の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をメタデータで分けました。

同様に、GitOpsのreconciliationを参考にしていても、文書を無条件に自動移動する仕組みにはしていません。実状態との差をAIが検出し、根拠が揃った変更だけを人間が承認する設計です。自動化するのは観測・比較・検証であり、曖昧な業務判断ではありません。

Diátaxisとも一対一のfolder対応にはしていません。利用者向けdocumentationの分類に加えて、内部の意思決定、計画、状態、監査証跡、生成物を管理する必要があったため、Anshinの開発・運用責務に合わせて分類を拡張しています。

これらは、特定標準への準拠や認証取得を主張するものではありません。それぞれの原則から、今回の問題に必要な部分を採用し、機械検証できるcontractへ落とし込んだものです。

926件を「人が判断できる画面」に変える

926件をJSONへまとめただけでは、人間が判断できるドキュメント管理にはなりません。

今回の棚卸しでは、15リポジトリ・25のドキュメントルートから926件の文書・生成物が検出されました。人間がこれらを一件ずつファイルで開き、正本か、計画中か、参考資料かを判断するのは現実的ではありません。

そこで、AIが収集・分類した結果を、人間が判断できる形へ変換するため、Adminにドキュメント管理画面を実装しました。

画面では、文書を次の5つに分類して確認できます。

正本
計画中
要確認
資料・生成物
履歴

リポジトリや状態で絞り込み、一覧から文書を選択すると、GitHubのように本文とGit差分を右側で確認できます。人間は926件すべてを読むのではなく、AIが絞り込んだ「判断が必要な文書」に集中できます。

ただし、Admin画面を文書の正本にはしませんでした。

現在の正本は、各リポジトリでGit管理されているMarkdown本文、frontmatter、配置です。Adminは、それらから決定的に生成されたinventoryとprivate bundleを表示する、読み取り専用のカタログです。

初回移行では「正本として移行」「削除対象」「要修正」「保留」といった判断機能も使用しました。しかし、移行完了後までDBで文書状態を管理すると、GitとDBのどちらが正しいのかという新しい問題が生まれます。

そこで通常運用では、DBを現在状態の管理から外しました。初回移行時の判断履歴だけを監査証跡として残し、新しい文書や更新された文書をDBへ登録する必要はありません。

Git管理されたMarkdown
        ↓
inventory・review bundleを自動生成
        ↓
Adminで検索・分類・本文・差分を確認

Adminからファイルの移動、削除、commit、pushは実行できません。

AIによる分類、人間による判断、Git変更、検証、公開を分離することで、管理画面の誤操作がそのまま文書破壊につながらない設計にしています。

初回移行時のAdmin画面。移行完了後は、Git上の文書を確認する読み取り専用カタログへ役割を変更しています。

すべてを仕様書にするわけではない

ドキュメント管理を強化すると、あらゆる実装に長い仕様書を要求しがちです。しかし、それでは文書の更新自体が目的になり、すぐに実装との差異が生まれます。

局所的で、コードの型や名前、コメント、テストを見れば振る舞いが一意に分かる変更は、それらを根拠として扱います。新しい正本仕様を作るのは、複数リポジトリに影響する変更、大規模な仕様変更、API・DB契約、運用・ロールバック、将来の判断に理由を残す必要がある場合です。

新しい開発作業では、AIはまずregistryとcanonical indexから関連文書を特定し、次に対応するコード・契約・テストを確認します。文書が不要な変更では無理に増やさず、必要な場合は実装と同じ変更単位で更新します。これにより、「文書を読めば分かる」と「コードを見れば分かる」のどちらについても、根拠を追跡できる状態にしました。

結果——AIに「毎回ゼロから調べさせる」開発から脱却した

今回の成果は、フォルダがきれいになったことではありません。

最も大きな変化は、AIへ機能改善を依頼するたびに、ソースコードから仕様を起こし直す必要がなくなったことです。

整備前は、AIが古い文書や重複した文書を参照する可能性がありました。そのため、人間が毎回、実装から仕様を復元させ、内容を確認してから、本来の開発依頼を行っていました。

機能改善を依頼
  ↓
AIが古い文書を参照
  ↓
誤った前提や実装が発生
  ↓
人間がソースコードから仕様を再確認
  ↓
新しい説明文書を作成
  ↓
さらに文書が増える

現在は、AIが最初にregistryとcanonical indexから正本候補を解決し、対応するコード、テスト、API・DB契約を確認します。

機能改善を依頼
  ↓
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が誤りを増幅する環境から、AIが正しい情報を蓄積し、次の開発を速くする環境へ移行できました。

まとめ

AI駆動のドキュメント整備は、AIに文章を書かせることではありません。今回の取り組みで得た要点は、次の3つです。

Git管理されたMarkdown、frontmatter、配置を文書の正本にする。
AIは走査・比較・矛盾検出を担い、正本や高リスク仕様の承認は人間が担う。
決めた規定を各リポジトリの./scripts/build_check.shで継続的に検証する。

曖昧な情報環境では、AIは誤りも速く増幅します。一方で、正本、責務、判断境界、検査方法が明確であれば、AIは文書を整え、次の開発へ知識を引き継ぐ存在になります。

重要なのは、AIを導入すること自体ではなく、AIが安全に力を発揮できる情報環境を設計することです。今回構築した仕組みを、今後の機能追加や仕様変更とともに継続的に育てていきます。