docs と履歴（1/2）
docs/ と ADR。
docs/ と z_docs/（作業履歴）
作業履歴の正本: Obsidian Vault
03_Operations/history/YYYY-MM/yymmdd-hhMM.md（MCP 連携可）。リポ内
z_docs/history/: ローカル退避・任意（Vault 未接続時）。新規書き込みは Vault を優先。
docs/: チーム公式。新規追加はユーザー明示時のみ（documentation-z-docs.mdc参照）。
立ち位置の違い
| 観点 | docs/ |
z_docs/ |
|---|---|---|
| 位置づけ | チーム公式（既存） | 作業履歴・個人メモ |
| 新規追加 | 原則禁止（ユーザー明示時のみ） | セッションごとに自由 |
| 主な読者 | チーム・新メンバー | 主に自分 |
| 品質バー | レビュー必須 | 再現できれば OK |
| PR 対象 | はい（既存更新時） | 原則いいえ |
| 代表的内容 | 要件・設計・ADR・運用 | 作業ログ・調査・下書き |
tasks/（Plan・振り返り）
| ファイル | 書くこと | 更新タイミング |
|---|---|---|
tasks/todo.md | チェックリスト、Plan メモ、レビュー・結果 | タスク着手時・Plan 確定時・完了時（Phase 2） |
tasks/lessons.md | ユーザー指摘・修正パターン・再発防止 | 指摘を受けた直後、セッション開始前に読む（エージェント運用） |
配置と判断フロー
配置ルール
docs/ # チーム公式（新規追加はユーザー明示時のみ）
├── README.md # docs/ 全体の索引
├── architecture.md # システム全体アーキ
├── glossary.md # 用語集
├── setup.md # 開発環境セットアップ
├── adr/ # ADR（詳細: 11.7）
├── operations/ # 運用手順
└── <feature>/ # 機能単位（既存）
tasks/ # Plan・振り返り（リポジトリ直下・テンプレ同梱）
├── todo.md
└── lessons.md
z_docs/
├── history/ # 作業履歴（必須）
│ ├── yymmdd-hhMM.md # セッション単位
│ └── yymmdd-hhMM-{概要}.md # 概要を明示したい場合
├── <feature>/ # 任意: 機能別の検討メモ
└── （直下のインデックス・長期メモはプロジェクトの慣習に従う）
判断フロー
flowchart TD
A[書こうとしている文書] --> B{セッションの作業ログか}
B -->|はい| H[z_docs/history/yymmdd-hhMM.md]
B -->|いいえ| C{チームの公式成果物か}
C -->|いいえ| Z[z_docs/ の任意の場所]
C -->|はい| D{ユーザーから docs 明示の指示があるか}
D -->|いいえ| W[まずユーザーに確認]
D -->|はい| E{意思決定の根拠か}
E -->|はい| F[docs/adr/]
E -->|いいえ| G[docs/<feature>/]
運用のコツ
- 履歴の正本は Obsidian
03_Operations/history/YYYY-MM/。ファイル名yymmdd-hhMM.md（概要付きはyymmdd-hhMM-{概要}.md）。リポ内z_docs/history/は任意のローカル退避 docs/への新規追加はユーザー明示時のみ: 既存docs/の修正・更新は通常のフローでよい。削除や移行はユーザー依頼時のみ- 個人グローバルルール（
~/.cursor/rules/documentation-z-docs.mdc）が常時適用される前提 - MCP（Obsidian）: Vault 内
03_Operations/history/を参照・追記。ボルトとリポz_docs/の二重化は任意（正本は Vault） - 長期メモ・索引:
z_docs/直下に置くかはプロジェクトの慣習またはユーザーの明示に従う
.gitignore での扱い（11.2 への追補）
docs/はコミット対象（チーム共有の正式な記録）z_docs/はプロジェクトの慣習に従う: ローカル限定にするなら.gitignoreへ。チームで履歴を共有するならコミット対象でもよい
# 例: 個人メモをローカル限定にする場合
z_docs/
# 例: 履歴だけ共有したい場合
# z_docs/*
# !z_docs/history/
ADR (Architecture Decision Records)
ADR とは
Michael Nygard 提唱のフォーマットが事実上の標準。
用語集の ADR / Architecture Decision Records も参照。