日本語 | English

HLDocS

Human–LLM Document Roles Specification

HLDocS は、人間（Human）と大規模言語モデル（LLM）が協調して
ドキュメントを作成・検証・再構成するための
役割分担（roles）と規約（rules）を定義する共通仕様である。

本リポジトリは、AIChaBo や Project Sansa を含む複数プロジェクトでの実運用を前提に策定されているが、
特定の実装・ツール・フレームワークには依存しない。

---

リリース状況

HLDocS は現在、**Preview Release（v0.x 系）**として公開されている。

現時点の状態：

• コア仕様：利用可能
• Traceability 基盤：利用可能
• ChatGPT UI ベース運用：利用可能
• 再生成・再構成運用：利用可能
• LLM_WORKSPACE 運用：利用可能
• 成果物更新運用：利用可能
• ドキュメント参照・ナビゲーション規約：利用可能
• prompt/template の完全自己完結生成：開発継続中

現在の推奨利用方法：

1. docs/ja-JP/仕様 を LLM に提示
2. HLDocS の生成プロンプト・テンプレートを利用
3. HLDocS 規約に従って生成・検証・再構成を行う

HLDocS は既に実プロジェクトで利用可能な状態にあるが、
一部の生成・検証・可視化ワークフローは継続的に改善中である。

---

HLDocSとは

HLDocS は、次の前提に基づくドキュメント仕様である。

• ドキュメントの 正規構造は LLM が保証する
• 人間は 構造を精読・検証しない
• 人間は 意味・妥当性・設計判断にのみ集中する
• 人間向けの可読性は「補助情報」として扱う

HLDocS は「人間が読むための書き方」ではなく、
人間と LLM が役割分担して扱うための書き方を定義する。

---

役割

Human（人間）の役割

• 要件・設計・テスト内容の妥当性判断
• 粒度・方針・合意形成
• レビューおよび意思決定

人間は、HLDocS において
ドキュメント構造の完全性や整合性を検証しない。

---

LLM の役割

• ドキュメント構造の維持
• ID・対応関係・構造情報の正確な保持
• 再構成・生成・検証の補助
• 人間向け補助情報の生成支援

LLM は、HLDocS において
構造破壊を起こさないことが最優先要件となる。

---

LLM_WORKSPACEと作業運用

HLDocSでは、長期間にわたる Human–LLM 協調作業を支援する。

推奨する作業運用は以下の通りである。

1. 新しい要求は Request に記録する
2. 現在の作業状態は Worklog に記録する
3. チャット移行が必要な場合のみ Handover を作成する

Worklog は作業状態の正本とする。

LLM_WORKSPACE は論理構造であり、 保存先は GitHub、添付ファイル、チャット等を利用できる。

GitHub が利用できない場合でも、 作業継続可能でなければならない。

---

正規情報と非正規情報

HLDocS では、ドキュメント内の情報を以下の 2 種類に分けて扱う。

Canonical（正規情報）

• 構造定義
• ID（Suite / Test / API 等）
• 対応関係
• 仕様上の宣言

正規情報は 唯一の正とする情報であり、
削除・変形・曖昧化してはならない。

---

Non-Canonical（非正規情報）

• Human-Note（判断補助・注意点）
• 要約・補足説明
• 可読性向上のための記述

非正規情報は、

• 削除されても仕様は成立する
• LLM により再生成可能
• 正規情報に影響を与えない

---

ドキュメント種別

HLDocS は、以下のようなドキュメント種別への適用を想定する。

• テスト仕様
• API 仕様
• 設計仕様
• コア仕様ドキュメント

各ドキュメント種別ごとに、

• 正規情報の範囲
• Human-Note の役割
• LLM に要求する保証 を明確に定義する。

---

Markdown運用方針

HLDocS のドキュメントは Markdown 形式を前提とする。

ただし、Markdown は装飾目的ではなく
構造を明示するための記述形式として使用する。

• 表（table）の使用は原則禁止
• 意味を持つ記号・記法は仕様で固定する
• 可読性向上のための装飾は非正規情報として扱う

---

HLDocSの対象外

HLDocS は以下を目的としない。

• 人間向けに「読みやすい」ドキュメントを書くこと
• 特定のツール・フレームワークの強制
• 法的拘束力を持つ規約の提供

HLDocS はあくまで
技術的・設計上の共通仕様である。

---

ロードマップ

v0.x Preview Series

現在の主な開発対象：

• 仕様再構成ワークフロー
• トレーサビリティ移行
• Markdown → HTML 可視化規約
• 運用ワークフロー安定化
• 検証フロー整備

Planned v1.0

v1.0 では以下を目標とする。

• prompt/template の完全自己完結生成
• 安定した再構成ワークフロー
• 完全な validation integration
• production-grade generation pipeline

---

今後の展開

本リポジトリには、将来的に以下が追加される可能性がある。

• 仕様チェック用プロンプト
• ドキュメント生成・再構成プロンプト
• 構造検証ツール
• 実装例（例：AIChaBo）

これらはすべて HLDocS の仕様を前提として設計される。

---

ドキュメント

• 目次

---

ライセンス

MIT License