---
title: "Shared Documents — 正本と投影、文書の契約"
description: "Shared Documentsの正本はserver、ローカルはprojection。WikiLinkのフルパス規則、kindと_template.md、警告と保存拒否の区別、編集競合の扱い。文書の契約に関する質問はこのページで答える。"
---

# Shared Documents — 正本と投影、文書の契約

Shared Documentsは、agentと人間が成果物を残し、引き継ぐための「流れない正本」である。timelineのメッセージが時系列に流れていくのに対し、Shared Documentsは確定した内容が置かれ、次のagentと人間が「真実」として読み直す場所である。

使い分けの規範はこうである。**確定した内容 — 決定、完成した仕様、引き継ぎ — をShared Documentsに置き、検討途中の内容はchat / sessionに留める。** また、人間への質問はdocumentのfrontmatterに書かず、必ずProject Asksを使う（`projects.md`）。

## 正本と投影の関係

**Shared Documentsの正本はserver側にある。** ローカルの `aachat/projects/` ディレクトリはprojection（投影）であり、`aachat up` 稼働中のみserverと双方向同期される。

- ローカルのファイルを編集すれば自動で同期される。手動のsyncコマンドは存在しない
- `aachat up` が稼働していない間のローカル編集は同期されず、稼働中に再同期される
- どちらが正かと問われたら、serverが正本、ローカルは投影と答える

この境界の全体像（何がserverに保存され、何がローカルで完結するか）は `trust-boundary.md` が正本である。

## 文書の場所とWikiLink

documentは次の階層で管理される。`<kind>` がそのdocumentの種別を表す。

```
aachat/projects/<team>/<project>/docs/<kind>/<id>.md
```

document同士はWikiLinkで相互参照できる。**WikiLinkはリポジトリ内パスをそのまま `[[ ]]` で囲んだフルパス形式のみで、短縮形はエラーになり保存が拒否される。**

```
[[aachat/projects/<team>/<project>/docs/<kind>/<id>.md]]
```

WebUIでは、document本文やメッセージ中のWikiLinkがクリック可能なチップとして表示される。agentへの依頼の本文にWikiLinkを書くと、agentはそのパスのdocumentを読んで文脈にできる。

documentパネルでは、そのdocumentを参照している他のdocumentの一覧が **Referenced by** として確認できる。本文のWikiLinkや `depends_on` などのフィールド経由の参照がチップで並び、どのフィールド経由かもバッジで分かる。仕様書から関連タスクへ、調査メモから判断documentへ、と双方向にたどれる。

## kindと `_template.md`

kindはdocumentの種別（`spec` / `task` / `research` / `meeting` など）である。**kindの定義は、そのkindのフォルダに `_template.md` を置くことで行う。** frontmatter先頭の `_aachat:` ブロックにメタデータを書き、それ以外のfrontmatterと本文が新規documentの雛形になる。

```yaml
---
_aachat:
  schema:
    type: object
    required: [title, summary, status]
    properties:
      title:   { type: string, minLength: 1, maxLength: 120 }
      summary: { type: string, minLength: 1, maxLength: 400 }
      status:
        type: string
        enum: [draft, approved, published]
title: ""
summary: ""
status: draft
---
## Context
```

`_aachat` に書けるキーは次の3つだけで、それ以外のキーはエラーになる。

| キー | 必須 | 内容 |
|---|---|---|
| `schema` | ○ | frontmatterの検証ルール（JSON Schemaのサブセット） |
| `template_policy` | − | 雛形の上書きポリシー。`always_overwrite`（省略時の既定。テンプレート更新のたびに配布済み雛形も上書き）または `create_once`（最初の1回だけ作成、以後上書きしない） |
| `preview_fields` | − | document cardのプレビュー対象にするフィールド名の配列 |

**未定義のkindは素のMarkdownとして扱われる。** kindを定義しなくてもdocumentは普通に使え、定義したkindだけにスキーマ検証と雛形が働く。

既製のkind定義一式は、Discoverの「テンプレート」からprojectにインストールできる（既存kindと名前が重複する場合は確認の上で上書きを選べる）。CLIでは `aachat template list|search|show|install|publish|update|unpublish` で一通り操作でき、自分のprojectで育てたkind定義を `aachat template publish` でDiscoverに公開できる。

## 警告と保存拒否の区別

documentの問題は「警告（保存は通る）」と「拒否（保存されない）」の2段階に分かれる。この区別を混同して答えない。

**警告（非ブロック）**: frontmatterがkindのschemaに合っていなくても、保存は拒否されない。ズレは警告として記録され、documentパネルの「Validation warnings」バナーと、timelineのdocument cardの警告行に表示される。agentの作業を止めずに、後から人間が直せる設計である。

**拒否（保存されない）**: 次の場合のみ保存自体が拒否される。

- kind名の命名規約違反（英小文字始まり。使えるのは英小文字・数字・`_`・`-`。32文字まで。`_` 始まりは不可）
- doc idの長さ超過（64文字まで）
- frontmatter自体の構文エラー
- 短縮形のWikiLink
- 1 document 1 MBの超過

ローカルのファイルで作業している場合、拒否や警告の内容は各kindフォルダの `_errors.md` に書き出される。これは自動生成のレポートファイルなので、手で編集せず、指摘された原因を直して保存し直す。問題が解消されると内容も消える。

## WebUIでの編集と競合検出

documentはWebUIのdocumentパネルから編集できる。編集中に他のメンバーやagentが同じファイルを先に保存すると、「changed elsewhere」というアラートが出て、自分の下書きを保ったまま次の3つから選べる。

| ボタン | 動作 |
|---|---|
| Reload latest | 最新の内容を読み込み直す（自分の編集は破棄） |
| Keep my draft | 自分の下書きを残したまま編集を続ける |
| Overwrite with my draft | 自分の下書きで上書き保存する |

黙って上書きされたり、編集が消えたりすることはない。

## timelineへの表れ方 — document card

agentや人間がdocumentを作成・更新すると、projectのtimelineに **document card** が流れる。cardには次が表示される。

- kindとstatus（選択肢が定義されていればcard上で直接変更できる）
- titleとsummary
- スキーマ警告がある場合はその1件目

cardをクリックするとdocumentパネルが開き、全文を確認できる。プレビューに出すフィールドはkind定義の `preview_fields` で指定でき、指定しない場合は `assignee` / `owner` / `priority` / `due_date` / `tags` / `depends_on` などのaachat既定のフィールドセットのうち、frontmatterに存在するものが表示される。

document本文には ` ```mindmap ` ブロックも書け、WebUIでは折りたたみツリーとして表示される。mindmapは考えるための作業面であり正本そのものではないので、方針が固まったらDecision / Nextを中心に通常本文へ圧縮させる。

## 関連ページ

- Shared Documentsが概念の中でどこに位置するか、文脈の2層構造 — `concepts.md`
- serverとローカルの境界の全体像（正本と投影を含む） — `trust-boundary.md`
- timeline・Asksなどprojectの表面 — `projects.md`
- WebUIの画面と操作 — `webui.md`
- CLIコマンドの詳細 — `cli.md`