AIが読める設計マニュアル
ソフトウェアの設計・仕様・導入手順を、人間だけでなくAIエージェントが直接読んで実行できる形で記述したドキュメント。
AIが読める設計マニュアルとは、人間だけでなくAIが直接読んで理解・実行できることを前提に設計された、ソフトウェアの設計・仕様・導入手順を記述するドキュメントである。
概要
通常の設計書は人間の開発者向けに書かれるが、AIが読める設計マニュアルは、AIがコードの意図・構造・変更手順を把握できるように、明確で構造化された形式で書かれる。これにより、AIが保守・改修・機能追加・設置などの作業を自律的または半自律的に行いやすくなる。Kurageでは、単なる付属資料ではなく、ai-modifiable-softwareを支える中核的な構成要素と位置づけている。
マニュアルは必ずしも一枚岩ではない。実測に基づく導入手順書、AIエージェントに作業を任せるための設置指示書、設定の変更点を宣言する設計マニュアル、動作確認のスクリプト、AI活用を学ぶ教材、そしてAIが直接ツールとして呼び出せるmcpサーバー同梱まで、目的に応じた複数の形態をとる。共通するのは「人ではなくAIに渡すことを前提に書かれている」という点である。
Kurageにおける位置づけ
Kurageは、このマニュアルをビジネスモデルの中核に位置づけている。
- vibe-prototype(バイブプロトタイプ制作サービス)の納品物には、ソースコード一式(MIT) とともに「AIが読める設計マニュアル」が含まれる。低価格・短期間で作った土台を、AIを使って顧客自身が改良できるようにする狙いがある。
- kurage-app-storeで販売される商品は、全商品にソースコードが同梱され、AIエージェントによる改変・拡張が可能とされている。「全商品ソース同梱・AIエージェントで改変拡張可」という一文が、ストア全体の販売方針として掲げられている(kurage-products)。
- 価格帯はマニュアルと密接に対応する。値付けは 5,500円 / 55,000円 / 110,000円 / 165,000円 / 220,000円 / 550,000円 の段階に分かれ、手順書の厚みと扱う判断の重さがそのまま価格の裏づけになる。5,500円のoss-japanese-localizationキットは実測手順書と落とし穴の記録、55,000円の業務システムは設計マニュアルと設置指示書、110,000円以上の製品では要件定義や複数エンジンをまたぐ手順書が同梱される。165,000円のkurage-disaster-judgment-setや220,000円の重説チェック(kurage-juyo-saigai-check)では、複数の判定エンジンとその据え付け手順が一式になる。550,000円のkurage-kokkai-trackerやkurage-giin-statement-logは、議員マスタの差し替え方まで含めた運用前提の文書を伴う。
- 商品一覧を見渡すと、ほぼすべての有料商品が「PHP+SQLiteの1ファイル」「MITライセンス」「ソース同梱」を共通の前提としている(self-contained-php-app)。マニュアルはこの構成を、顧客が現実に動かし・直せる形へ橋渡しする文書でもある。
三点セットとしての商品
kurage-productsを通して見えるのは、商品が「ソースコード+設計マニュアル+公開デモ」の三点セットで提示されていることである。ほぼ全商品にデモURLが用意され、「デモを触ってからご判断ください」という一文が繰り返される。マニュアルは、デモで確かめた挙動を自分のサーバーで再現し、その先を自分で変えるための手引きという位置にある。
商品への展開
kurage-productsの商品一覧によると、Kurage App Storeで販売されるほぼすべての商品がMITライセンスでソースコードを公開し、AI向けの設計マニュアルまたは手順書を同梱している。有料商品の多くには特に「Claude Code向け設計マニュアル」や「AIに渡せば設置まで進む手順書」が含まれる。
代表的な例は以下のとおり。
- kcaldav — 「同梱のClaude Code向け設計マニュアル」で設定変更や機能追加をAIエージェントに依頼できる。
- kreserve — 設定ファイルの役割を集約し、「Claude Code等のAIエージェントに頼んで安全に変更できる設計マニュアル同梱」。
- kbilling、kpaylink、kinvoice — 「AIに渡せば設置まで進む手順書」を同梱。kinvoiceには実際に踏んだ6つの罠の記録も含まれる。
- ktrackgeo、kcheckit — 「VWork教材」が同梱され、AI活用の学習材料となる(vwork)。
- kurage-vibe-groupware-core — 設置から運用、AIにアプリを書かせる手順まで、全10ファイル・約1,350行の手順書を同梱。
- kurage-memo — 「AI向けの改造手順書と検証26件」を同梱し、他社サービスに預けず自社サーバーで動かすための改変手順を提供。
- kurage-fillout — 申請書のWord・Excel・PDFを書式のまま埋めるツールで、AIに文章は作らせないという方針をマニュアルで明示する。
- kurage-hr-post、kurage-kintai、kurage-ai-meishi-analysis、kurage-crm-agent、kurage-light-chatbot、kbbs、kdbagentなど、他の商品もソース同梱・AIによる改変拡張が可能な構成である。
- ナビ系の商品(kurage-seido-navi、kurage-subsidy-navi、knyusatsu、kshoken、kurage-ai-mom など)も、データの差し替えやAIエージェントからの呼び出しを前提とした説明を備える。
実測手順書と「落とし穴」の記録
oss-japanese-localizationキット(5,500円)では、公式ドキュメントには書かれていない失敗を実機で踏み、その回避手順を番号つきで収録する型が繰り返される。
- alaveteli 日本語導入キット — 落とし穴6個と、AIに渡せる設置指示書。
- fixmystreet 日本語導入キット — 落とし穴8個と、AIに渡せる設置指示書。
- freescout-japanese-kit — 落とし穴10個の回避込みの手順書、要件チェックツール、403修正スクリプト。
- espocrm-japanese-kit、krayin-crm-japanese-kit — 落とし穴10個・11個と、本番で動いている設定ファイルの実物。「フォルダごとClaude CodeやCodexに渡せば、AIが手順書を読んで構築まで進む」と明記。
- kouchou-ai-local-kit — 踏んだ罠11個を実測ベースで収録。
- appsmith、paperless-ngx、pdfmathtranslate-japanese-kit、docspell-japanese-kit、planka-japanese-kit、vikunja-japanese-kit、docmost-japanese-kit、codealmanac-japanese-kit、libredesk-japanese-kit、decap-cms-japanese-kit、billionmail-japanese-kit、theyworkforyou などのキットも、動作判定スクリプトや復旧手順を含む同種の構成をとる。
これらは「AIが読んで実行する」だけでなく、「AIが間違えやすい箇所を先に潰しておく」ための文書でもある。エラーが出ないまま壊れる種類の失敗(日本語OCRの無言スキップ、初回起動20秒の中断による恒久破損、BASE_URL不一致による白画面など)が特に重視されており、measured-pitfall-catalogとして商品価値の中心を成している。
設計思想を書き残す文書
商品一覧が繰り返し掲げる設計原則は、コードだけでなくマニュアルにも書き残される。AIが改変する際に思想ごと壊さないようにするためである。
- 決定論的な判定 — 避難判断や達成率、感染症の数値などはコードが決定的に計算し、AIに結論を採点させない(deterministic-core)。防災AIチャットや判定セットでは「AIは結論を言い換えるだけで変えない」「AIが止まっていても規則の答えとカードはすぐ出る」ことが明記される。
- 未収録と区域外の区別 — 「該当なし」「区域外」と書かず、未収録・判定対象外・データなしを分けて答える方針が手順書に織り込まれる(unknown-vs-outside-distinction)。重説チェックでは、確認できないものを空欄や「該当なし」で流すと重要事項説明の誤りに直結するため、確認漏れが紙の上に残る作りにしていると説明される。
- データ時点と出典の明示 — 判定には必ずデータの時点を添え、時点不明なら判定しない(evidence-traceability)。時点が確認できないデータでは判定しないという規則自体が文書化される。
- 外部に送らない前提 — 住所・音声・顧客情報・意見データをサーバー外に出さない構成が説明される(no-external-data-egress)。生成AIをローカルのモデルに限定する理由もここに書かれる。
- 取得できないときは「取得できない」と書く — 避難情報や河川水位が取れなかったとき、「発令なし」「異常なし」と書かない規則を明示する。
- 増えた側と消えた側の両方を見る — 消えた事業所を記録し、理由が公表されない限り「廃止した」と書かない(facility-data-churn)。
- 設定ファイル1枚で差し替える — 自治体データ・社名・ロゴ・計測タグ・取り出す項目を設定で外出しし、他地域・他業種へ展開できるようにする(municipality-data-swap-expansion、config-declared-scope)。差し替え手順そのものがマニュアルの主要な章になる。
MCP同梱という新しい形態
マニュアルを読ませるだけでなく、AIが同じ計算・判定をツールとして直接呼べるよう、mcpサーバーを同梱する商品が増えている。
- kdbagent — 設定で宣言した範囲の操作だけをMCP経由でAIに実行させる。config-declared-scopeの代表例。
- karchitect — 逆方向の例で、AIとの対話から要件JSONとシステム設計書(Markdown/HTML/PDF/Mermaid)を生成する。AIが読む側ではなく、AIが設計マニュアルを書く側に回るツールである。
- kurage-ai-mom、kurage-line-crm、kurage-giin-statement-log、商圏分析(kshoken)、kcaldav、kurage-disaster-judgment-set、knisa、kurage-earthquake-mapなども、読み取り専用または限定されたMCPを同梱し、AIエージェントが実データを根拠に答える構成をとる。
これらのマニュアルは、config-declared-scopeと組み合わせることで、AIが宣言された範囲だけを変更し、範囲外を壊さない仕組みを実現している。kdbagentのように、設定ファイルで「表・列・操作」を宣言する設計は、AIエージェントに安全に任せるための典型例である。また、こうしたマニュアルはsales-partner-systemにおいて代理店が顧客に説明する際の重要な訴求材料にもなっている。販売代理店向けの商品カタログが存在すること自体、マニュアルの有無が販売力に直結することを示している。
関連する概念・エンティティ
- kurage — このマニュアルを提供する企業
- vibe-prototype — マニュアルが同梱されるプロトタイプ制作サービス
- kurage-app-store — 全商品に設計マニュアルが同梱されるストア
- kurage-vibe-groupware-core — 大規模な手順書を同梱するグループウェア商品
- karchitect — AIとの対話から設計書そのものを生成するツール
- kdbagent — 宣言範囲内でAIにDB操作を許すMCP同梱ツール
- kurage-disaster-judgment-set — 複数エンジンの据え付け手順を一式で同梱する例
- ai-agent — マニュアルの主な読者となるAIエージェント
- ai-modifiable-software — マニュアルによって実現される、AIが改変できるソフトウェアの考え方
- config-declared-scope — マニュアルと併用される安全な変更範囲の制限手法
- mcp — マニュアル同梱に代わる、AIが直接呼び出すインターフェース
- oss-japanese-localization — 実測手順書と落とし穴の記録を伴うキット群
- measured-pitfall-catalog — 手順書に番号つきで収録される、実測した失敗の目録
- self-contained-php-app — マニュアルが対象とする、1ファイル完結型のPHPアプリ
- municipality-data-swap-expansion — 設定差し替えによる他自治体展開の手順
- kappstore-ecosystem — マニュアル同梱を前提に成立する販売の仕組み
- sales-partner-system — 代理店が紹介する際の商品価値の一部として、このマニュアルが訴求ポイントになりうる
- deterministic-core — マニュアルが伝える「AIに結論を変えさせない」設計
- evidence-traceability — データ時点と出典を明示する方針
- unknown-vs-outside-distinction — 「該当なし」と書かないための区別
- no-external-data-egress — 外部に送らない前提を支える設計
- facility-data-churn — 消えた側も記録する方針
- vwork — 一部商品に同梱されるAI活用の教材
- kurage-agency — 本概念の初期の出典ドキュメント
- kurage-products — Kurage App Store商品群におけるマニュアル同梱の詳細
See also: kurage-sites
Kurage.AI に質問する
