# Reusable Doc Structure

> ドキュメントの構造が、目的・読み手・更新頻度の変化に対して再利用・転用できる設計になっているかを評価・設計する。一度書いて終わりではなく、継続して使えるドキュメント設計を目指す。繰り返し使うドキュメントを設計するときに使う。

- Skill: `thinkyou0714/reusable-doc-structure` (Agent Skill)
- Install (CLI): `npx skillmds@latest add thinkyou0714/reusable-doc-structure`
- Raw SKILL.md: https://api.skillmd.com/api/skills/thinkyou0714/reusable-doc-structure/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: thinkyou0714 (https://skillmd.com/u/thinkyou0714)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/thinkyou0714/reusable-doc-structure

---


## Purpose

「毎回ゼロから書く / 更新するたびに構造が崩れる」を防ぐ。
ドキュメントが変化に強く、別の文脈・読み手・AIセッションにも転用できる構造になっているかを評価・設計する。

## Use When

- 新規ドキュメントの構造を設計する場合
- 既存ドキュメントが肥大化・陳腐化してきた場合
- 複数のドキュメントで似た情報が重複している場合
- 別のAI・人間に引き継ぐためのドキュメントを整備する場合

## Inputs

以下を準備すること。不足している場合は推測せず、不足を明示する。

- **ドキュメント一覧または対象ドキュメント**: 評価・設計の対象
- **更新頻度**: 各ドキュメントがどの頻度で変わるか（日次 / 週次 / 変更時のみ / 固定）
- **読み手の種類**: 人間（エンジニア / 非エンジニア）/ AI（Claude / 他LLM）
- **再利用の目的**: 別プロジェクトへの転用 / テンプレート化 / 引き継ぎ / 自動化入力

## Output Contract

以下の順で出力すること。順序を変えない。

1. **論点**: このドキュメント構造の再利用性を左右する核心的な問題
2. **根拠**: その論点をそう判断した理由
3. **構造評価**: 評価項目ごとのチェック結果
4. **含意**: 構造の問題が引き起こす長期的なドキュメント負債リスク
5. **改善案**: 再利用性を高める最小限の構造変更案
6. **代替案**: 目的・更新頻度が異なる場合の別構造案
7. **判断材料**: 「現構造を維持 / 部分的に再設計 / 全体から再設計する」を選ぶための情報

### 構造評価 フォーマット

| チェック項目 | 状態 | 備考 |
|---|---|---|
| 変化する情報と固定情報が分離されている | OK / 注意 / NG | |
| セクションが独立して更新・参照できる | OK / 注意 / NG | |
| 他ドキュメントへの参照が相互依存になっていない | OK / 注意 / NG | |
| テンプレート化・変数化できる部分が特定されている | OK / 注意 / NG | |
| 情報の所在が一元化されている（重複がない） | OK / 注意 / NG | |
| 削除・統合・分割のコストが低い | OK / 注意 / NG | |
| 他LLMが構造を解析して正しく処理できる | OK / 注意 / NG | |

## Review Lens

- **目的妥当性**: 構造設計の評価基準がドキュメントの用途に対して適切か
- **範囲の過不足**: ドキュメントセット全体の構造が評価されているか
- **中長期リスク**: 半年後・1年後に構造が崩れるリスクはないか
- **LAB全体との整合性**: CLAUDE.md / CONTEXT.md / TASKS.md の構造設計原則と整合しているか
- **非エンジニア理解可能性**: 構造の設計意図を非技術者に説明できるか
- **他LLM移植耐性**: 構造が特定のAIの処理前提に依存していないか

## Instructions

1. ドキュメントを「変化する情報」と「固定情報」に分類する
2. 各セクションが独立して更新できるか（他セクションに依存していないか）を確認する
3. 複数ドキュメントに重複している情報を特定し、一元化の案を提示する
4. テンプレート化できる部分（パターンが繰り返される箇所）を特定する
5. 他LLMが構造を誤解なく処理できるかを確認する
6. 変更コストの低い改善案（見出し追加・分割・統合）から提示する
7. 最終判断は人間に委ねる

## Guardrails

- 構造の美しさのために情報を削除・省略する改善案を提示しない
- 「将来のために」過剰に抽象化した構造を推奨しない（現在の用途に対して最小限の設計）
- 参照の循環（A→B→A）を含む改善案を提示しない
- 更新頻度の異なる情報を同じドキュメントに混在させることを推奨しない
- 既存の構造を全面置き換えする場合は、移行コストを明示する

## LAB Cross-Check

| 観点 | 状態 | 備考 |
|---|---|---|
| 自動化フロー | — | 自動化設定・フロー定義の構造が再利用しやすいか |
| データ / 認証 / ログ | — | スキーマ・RLS・ログ仕様のドキュメントが分離されているか |
| 実装 / 運用フロー | — | 実装手順・運用手順が独立したドキュメントになっているか |
| 非エンジニア理解可能性 | — | ドキュメント構造の設計意図を説明できるか |
| 会員共有 / 再利用耐性 | — | 構造が他プロジェクト・他チームに転用できるか |
| 他LLM移植耐性 | — | 構造が Claude 固有の処理前提に依存していないか |

状態は OK / 注意 / NG / 対象外 で記入すること。

## Handoff Notes

- **要件**: 構造評価結果（チェック項目の状態）と再設計案
- **成功条件**: ドキュメントが更新・転用されても構造が崩れない
- **失敗条件**: 構造変更後に参照リンク切れ・重複・不整合が発生する
- **実行範囲**: ドキュメント構造の評価・設計案提示のみ（直接編集は行わない）
- **影響範囲**: ドキュメントを参照するすべての人間・AIセッション
- **ロールバック方針**: 構造変更後に問題が発生した場合は旧構造の git 履歴から復元
- **コスト比較**: 構造設計コスト vs 陳腐化したドキュメントを毎回書き直すコスト

## Further Reading

- `onboarding-readability` skill — 設計後の可読性チェック
- `llm-portability-review` skill — 他LLMへの移植耐性チェック
- `summary-structuring` skill — ドキュメント内容の構造化要約
- [docs/CONTEXT.md](../../../docs/CONTEXT.md) — ドキュメント設計の実例
- [docs/DECISIONS.md](../../../docs/DECISIONS.md) — 設計決定記録の構造例