🕌

Zettelkasten でモノレポのドキュメント管理方針を設計

に公開
docs
Zettelkasten
llm
SDD
idea

LLM 駆動開発が当たり前になってきた今、「ドキュメント管理の正解って何だっけ？」という感覚は多くの開発者に共通していると思います。
この記事は、モノレポで実装されたプロダクトに仕様ドキュメントと LLM 指示が増えていく状況を前提に、
「情報が散らかりにくく、LLM が必要な知識を必要なだけ参照できる状態」をどう作るかを整理したものです。

対象読者は主に開発者ですが、プロダクト関係者が LLM 経由で仕様確認するケースも想定します。
人間にとって読みやすく、運用しやすい情報整理方針であることも目的に含めています。

Zettelkasten って何？

Zettelkasten は「1 ノート=1 アイデア」を原則に、ノート同士をリンクで結び、知識を育てていく方法論です。参考: https://zettelkasten.de/posts/overview/
要点はシンプルで、次の 3 つに集約できます。

  • 原子化: 1 ノートに 1 つの主張や仕様だけを書く
  • リンク: 関連ノート同士を相互参照する
  • 成長性: 既存ノートに結び付けて知識体系を拡張する

なぜ今回の課題に向いているのか

今回の課題は「仕様が増えるほど、体系的に整理する方針が必要になる」「LLM 指示が増えるほど、冗長な記述が積み上がる」ことです。
Zettelkasten は、まさにこの問題に効きます。

  • 仕様を原子化できる: 機能単位の仕様を小さく保てる
  • リンクで関係性を表現できる: サービス/API/プロダクトの関係が整理できる
  • 体系化と再利用がしやすい: まとめは後から作れるので、拡張に強い

つまり「仕様が増えるほど、より体系的に整理される」構造が作れるというのが最大の理由です。

加えて、体系的にまとまった知識は LLM に与えるコンテキストとしても優秀です。
LLM が必要な知識を必要なだけ取得するために、原子化とリンクという Zettelkasten の考え方は相性が良いと考えています。

この文章での Zettelkasten 解釈

ここでは Zettelkasten を「仕様の原子化」として使います。
機能単位の仕様を ZK ノートとして書き、それを spec や index で束ねる構造にします。

ポイントは以下の通りです。

  • ZK ノートが一次情報
  • spec や index は導線
  • LLM 指示は読み方だけを書く

背景と問題意識

モノレポでは、仕様・設計・運用が体系的に整理されないまま散在しやすいです。
さらに LLM を導入すると、.claude/, .cursor/, .codex/, .gemini/, agent.md, skills などが乱立します。
そうなると、

  • どこが真実かわからない
  • 指示が矛盾する
  • 情報が体系化されず、保守運用が大変になる

といった問題が起きうると想定できます。

今後、プロダクトが増える前提で「一次情報の置き場」を設計しておく必要があります。

設計原則

  1. 一次情報は docs に集約する
    仕様・意思決定・制約はすべて docs に置く。人間も LLM もここを読む。

  2. LLM 指示は“読み方”に限定する
    LLM 向けファイルは「何を優先し、どこを参照し、いつ質問するか」を定義し、内容は docs に寄せる。

  3. 仕様は原子化し、リンクで結合する
    仕様は機能単位を基準とした ZK ノートで記述し、サービス/API/プロダクトとの関係をリンクで明示する。

  4. spec は“導線”に徹する
    spec は ZK ノートを束ねる概要・導線に限定し、詳細仕様の重複を避ける。

  5. “自明”の判断をルール化する
    冗長化を避けつつ、漏れや属人化を防ぐため、書くべき/書かない条件を明文化する。
    参考: https://diataxis.fr/

ディレクトリ構成（モノレポ最適化案）

docs/
  zettels/
    ZK-YYYYMMDD-<slug>.md
  indexes/
    product.md
    services.md
    apis.md
    features.md
    operations.md
  specs/
    S-<feature>.md
  adr/
    ADR-YYYYMMDD-<slug>.md
  llm/
    README.md
  glossary.md

役割

  • zettels/: 原子仕様（ZK ノート）
  • indexes/: 入口/一覧（薄いナビゲーション）
  • specs/: まとめ仕様（導線と全体像）
  • adr/: 意思決定の記録
  • llm/: LLM 向け共通入口（参照順序と禁止事項）
  • glossary.md: 用語集（ZK へのリンク）

図: 情報の流れと参照関係

LLM 指示ファイルの置き場と運用方針

指示ファイルはプロダクトごとに分かれていてもよいが、一次情報は必ず docs/ に集約します。
各 LLM の指示は「読み方・禁止事項・手順」に限定し、内容の重複を避けます。
Docs-as-Code の実装例として Backstage TechDocs の思想も参考になります。参考: https://github.com/backstage/backstage/tree/master/docs

  • .cursor/rules/: Cursor 用の作業ルールや手順。仕様知識は置かない
  • .claude/commands/: Claude 用の実行手順。仕様知識は置かない
  • skills/: 共通ワークフロー定義。共通知識は docs/ に寄せる
  • .claude/skills/, .codex/skills/: プロダクト固有のスキル定義。共通知識は持たない
  • .codex/, .gemini/: 追加される場合も同様に薄く保つ

図: LLM 指示レイヤのディレクトリ構成イメージ

.
├── docs/
│   ├── llm/README.md        # LLM 共通の入口（優先順位・禁止事項）
│   └── zettels/             # 仕様の一次情報
├── .cursor/
│   └── rules/               # 作業ルール（知識は持たない）
├── .claude/
│   ├── commands/            # 実行手順（知識は持たない）
│   └── skills/              # Claude 固有のスキル
├── .codex/                  # 追加される場合も README 参照のみ
│   └── skills/              # Codex 固有のスキル
├── .gemini/                 # 追加される場合も README 参照のみ
│   └── skills/              # Gemini 固有のスキル
└── skills/                  # 共通ワークフロー定義（共通知識は docs へ）

Zettelkasten の使い方

命名規則（ID 設計）

ZK ノートは 日付 + 説明スラッグ を推奨します。

例:

  • ZK-20250314-pacemaker-pacing-decision.md
  • ZK-20250314-frontapi-budget-update.md

運用ルール

  • タイトル変更でもファイル名は原則変更しない
  • 意味変更は新規ノートで対応する

この方式は「人間の可読性」「LLM の推測性」「リンク安定性」を両立できます。
原子化の実装例として、GitLab のドキュメントスタイルガイドや Markdoc の設計も参考になります。
参考: https://docs.gitlab.com/development/documentation/styleguide/ , https://markdoc.dev/

仕様ノート（ZK）の標準テンプレ

# ZK-YYYYMMDD-<slug>

## Summary
(1-2 sentences)

## Context / Background
(Why it exists)

## Scope
(Inclusions / Exclusions)

## Behavior / Rules
- Rule 1
- Rule 2

## Interfaces
- API: xxx
- Event: yyy
- Data: zzz

## Constraints
- Performance / Security / Compatibility

## Failure / Edge Cases
- Case 1
- Case 2

## Operations
(If small, keep here. If large, link to runbook.)

## Related
- Spec: S-<feature>
- ADR: ADR-YYYYMMDD-<slug>
- ZK: ZK-YYYYMMDD-<slug>

## Status / Updated
- Status: draft / active / deprecated
- Updated: YYYY-MM-DD

リンクのメンテナンス指針

Zettelkasten はリンクが命ですが、手動リンクだけで運用すると破綻しやすいです。
そこで「自動化 or 静的解析」を前提にします。

  • エディタ拡張でリンク補助を使う（例: VS Code の Markdown Notes 系）
  • CI でリンク切れチェックを行う

参考: https://docs.gitlab.com/development/documentation/styleguide/

spec と ZK の関係

spec は“まとめ仕様”で、ZK は“仕様の実体”です。

spec に許容する内容

  • 全体像（構成・フロー）
  • 重要リンクの整理
  • 依存関係の説明
  • 変更履歴のマイルストーン

spec に禁止する内容

  • ZK と重複する詳細ルール
  • 変更のたびに書き直すべき詳細記述

spec は導線であり、詳細は ZK に寄せます。

ADR の扱い

ADR は仕様とは分離しますが、必ず ZK や spec からリンクします。

# ADR-YYYYMMDD-<slug>

## Context
(Problem and constraints)

## Decision
(What we decided)

## Consequences
(Tradeoffs, risks)

## Related
- ZK-...
- Spec-...

LLM レイヤ設計

共通入口（docs/llm/README.md）

LLM が読むべき参照順序と禁止事項を 1 ファイルに集約します。
各プロダクトの指示ファイルは この README を参照するだけ にします。

例:

# LLM Usage Guide (Monorepo)

## Scope
Primary sources are in:
- docs/indexes
- docs/specs
- docs/zettels
- docs/adr
- docs/glossary.md

## Priority
1) docs/indexes
2) docs/specs
3) docs/zettels
4) docs/adr
5) docs/glossary.md

## Freshness
Prefer notes with newer Updated dates. If conflicts exist, trust zettels over specs.

## Do / Don't
- Do ask questions when information is missing or ambiguous.
- Do link to source notes in answers.
- Don't infer specs from code unless explicitly requested.
- Before answering, read `docs/indexes/features.md` and identify relevant zettels to consult.

## Link Policy
Specs should link to zettels; zettels are the atomic source of truth.

## Audience
Primarily developers; PM/Ops access via LLM interfaces.

.cursor/ と .claude/ に関する想定ケースと改善案

現状、以下が重複しています。

  • AGENTS.md と .cursor/rules/base-rules.mdc にプロジェクト構成や方針が重複
  • .cursor/rules/base-rules.mdc が一次情報（構成/コマンド）と LLM 指示を混在させている
  • .claude/commands/* が .cursor/rules/* を参照し、指示が多層化している

改善提案

  • プロジェクト構成/コマンド/仕様は docs/ に集約
  • .cursor/ と .claude/ は 読み方/手順/禁止事項 のみに限定
  • .cursor/rules/base-rules.mdc は薄くし、docs/llm/README.md を参照させる
  • .claude/commands/* は操作手順に特化させ、知識は docs へ寄せる

今後 .gemini/ や .codex/ が追加される場合の方針

  • 新規プロダクト用の指示ファイルは 必ず docs/llm/README.md を参照
  • 仕様や構成の記述を新規に持たせない
  • 例外は「そのプロダクト固有のツール制約や実行手順」のみ
  • これにより、指示の重複・矛盾・肥大化を回避できます

LLM 時代のコンテキスト制御

LLM のコンテキストは「大きければ良い」というものではありません。情報量が増えるほど注意が薄まり、
必要な情報を見失うリスクがあります。だからこそ、ドキュメント構造側で 段階的開示 を前提にします。

  • 入口 → 仕様 → 原子ノート の順で辿れる構造にする
  • 常に全文を渡さず、必要に応じて深掘りさせる
  • 静的な知識（規約や構成）と動的な依頼（作業内容）を分離する

この方針は、Context Engineering や Prompt Caching の考え方とも整合します。
参考: https://arxiv.org/abs/2307.03172 , https://platform.claude.com/docs/en/build-with-claude/prompt-caching , https://github.com/letta-ai/letta

Zettelkasten と RAG の接続点

Zettelkasten の「原子化」は、RAG のチャンキング戦略と同じ課題を解いています。
特に構造認識チャンキングや意味的チャンキングの考え方は、ZK ノートと相性が良いです。

結果として、検索の精度と文脈の再利用性が両立しやすくなります。

指示と知識の分離（セキュリティと運用の両面）

LLM は指示とデータが混ざると、誤って命令として解釈する可能性があります。
そのため、指示（rules/commands）と知識（docs）を物理的に分離します。

  • 指示は「読み方・禁止事項・手順」に限定
  • 知識は docs/ に集約
  • 参照は docs/llm/README.md を入口に統一

この構造は、プロンプトインジェクションのリスク低減にもつながります。
参考: https://docs.anthropic.com/claude/docs , https://platform.openai.com/docs/guides/prompt-engineering

“自明な仕様を省く”ためのルールと運用イメージ

書くべき仕様

  • 例外がある
  • 意見が割れやすい
  • 将来変更される可能性が高い
  • コスト/リスクが高い

書かない仕様

  • 一般論（誰でも同意する）
  • 実装から完全に自明
  • 仕様というより手順だけの話

この基準を明文化して、冗長化と属人化を抑えます。

想定する保守・運用フロー

ドキュメントは以下の流れで更新される想定です。

  1. 仕様変更や新機能が発生したら、まず ZK ノートを追加・更新する
  2. 既存の spec があればリンクを更新し、必要なら概要を調整する
  3. 重要な判断は ADR に残し、ZK/spec からリンクする
  4. index は入口として最低限のリンクのみ更新する

この順番にすることで、詳細が先に更新され、導線は後から追随する構造になります。

コードとドキュメントの同期ルール

モノレポでは「コードだけ消えて ZK ノートが残る」状態が起きがちです。
そこで、以下を明示的な運用ルールにします。

  • 機能削除の PR には、関連 ZK ノートの deprecated 化または削除を含める
  • 仕様変更の PR には、ZK と spec の更新を必須にする

品質ゲートの追加（運用の安定化）

ドキュメントが増えるほど品質は揺らぎます。そこで CI での簡易チェックを入れると運用が安定します。

  • Markdown の構造チェック（見出し階層、コードブロックの言語指定）
  • メタ情報の必須化（Updated/Status など）
  • LLM による「曖昧さ」評価（必要なら）

入口設計（indexes）

入口は“薄く、機能単位を中心に”設計します。

  • features.md : 仕様の第一入口（最重要）
  • services.md : マイクロサービス一覧
  • apis.md : API と IF の入口
  • operations.md : 重い運用への入口
  • product.md : 全体概観

まとめ

モノレポでは、仕様を Zettelkasten 型で原子化し、spec を導線として整理することで、
漏れのない体系と更新しやすさを両立できます。

LLM 指示は“読み方”に限定し、一次情報を docs に集約すれば、
LLM プロダクトの乱立によるコンテキスト肥大化も防げます。

この構造は、開発者が直接読むだけでなく、プロダクト関係者が LLM 経由で仕様を把握する場面でも機能します。

参考（本文中で言及したソース）

Discussion