--- 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に留める。** handoffはsession transcriptに残り、project全体への短い通知ならmessage、独立して読み返す長さと寿命がある場合は通常のShared Documentを使う。また、人間への質問はdocumentのfrontmatterに書かない。session内のagentはProject Asksを使い（[Projects](/ja/docs/projects)）、外側agentはホストaskを使う。 ## 正本と投影の関係 **Shared Documentsの正本はserver側にある。** ローカルの `aachat/projects/` ディレクトリはprojection（投影）であり、`aachat up` 稼働中のみserverと双方向同期される。 - ローカルのファイルを編集すれば自動で同期される。手動のsyncコマンドは存在しない - `aachat up` が稼働していない間のローカル編集は同期されず、稼働中に再同期される - どちらが正かと問われたら、serverが正本、ローカルは投影と答える この境界の全体像（何がserverに保存され、何がローカルで完結するか）は [trust-boundary](/ja/docs/trust-boundary) が正本である。 ## 文書の場所とWikiLink documentとして受け付けられるpathは次のとおり。 ``` aachat/projects///docs/PROJECT.md aachat/projects///docs/REPORT.md aachat/projects///docs/.md aachat/projects///docs//.md ``` - `PROJECT.md`はon-demandで最初に読むProject Contract / Context Router - rootの`.md`はkindを持たないroot document - `/.md`はfolder / kind配下のdocument - `docs/index.md`は全documentを列挙する自動生成の網羅的catalogで、手で編集しない WebUIのCreate Documentではroot、既存folder、新しいfolderを選べる。folderに`_template.md`があればkindとしてschemaと雛形が働き、無ければraw Markdown folderとして使える。 ### `PROJECT.md`は安定したProject Contract `PROJECT.md`は、project contextがtaskに必要なときだけagentが最初に読む。次の安定情報に限定する。 - Purpose - Outcome - Outputs - 判断原則とboundary - 重要な正本だけへ案内するcurated Context Map - 安定したApproach 進捗、担当、handoff、ログ、未解決メモは置かない。Context Mapは読み順を示す厳選リンクであり、documentの全件一覧ではない。そこに無いdocumentを探すときはgenerated `docs/index.md`を使う。 ### `REPORT.md`は成果と残る差の現在地 `PROJECT.md`が安定した目的と受け入れ条件を示すのに対し、`REPORT.md`は成果、確認した根拠、残る差、次の扱いを示す。**current Project Leadだけが作成・更新・削除できる**。正確な保存先は`aachat/projects///docs/REPORT.md`であり、`report.md`・`Report.md`やkind配下の文書で代用しない。 WebUIではProjectの**Docs**でREPORTのタイトルを探して本文を開く。本文がない、または古い場合はcurrent Leadに更新を依頼する。Leadの通常のファイル編集が既存の自動同期へ流れるので、手動syncやREPORT専用commandは不要である。反映されなければ[同期の復旧](/ja/docs/troubleshooting)を確認する。 Leadを持つactive Projectの完了にはREPORTが必要だが、その存在は成果達成の自動判定ではない。[Projectで成果を受け入れてDoneにする手順](/ja/docs/projects)に沿って、本文と成果物を確認する。 ### WikiLinkで文書をつなぐ document同士はWikiLinkで相互参照できる。**WikiLinkはリポジトリ内パスをそのまま `[[ ]]` で囲んだフルパス形式のみで、短縮形はエラーになり保存が拒否される。** ```text [[aachat/projects///docs//.md]] ``` WebUIでは、document本文やメッセージ中のWikiLinkが文書チップとして表示される。参照先が存在し、読む人・agentに閲覧資格があれば、チップや完全パスから本文を読める。依頼にWikiLinkを書くだけでは、参照先の作成や閲覧権限の付与は行われない。未解決表示の読み方は[Markdownブロック](/ja/docs/markdown-blocks)を参照する。 documentパネルの **Referenced by** は、登録された参照のうち、閲覧者が参照元Projectへアクセスできるものを示す。本文のWikiLinkや `depends_on` などのフィールド経由の参照がチップで並び、フィールドはバッジで分かる。参照の登録と各文書へのアクセス条件が揃えば、仕様書と関連タスクなどを双方向にたどれる。 ### 保存・参照登録・閲覧を分けて確認する **保存成功は、リンク先の実在・閲覧資格・Referenced byへの表示を保証しない。** 保存と参照登録を分離したserver版では、正しい完全パスのWikiLinkなら、参照先のTeamやProjectが見つからない場合や、保存する人・agentの権限範囲外でも、WikiLinkを含む本文を保存できる。利用環境に対応版が提供されているかは別途確認する。 参照登録では、削除されていないTeam、activeなProject、保存する人・agentのactiveなProject membershipを確認する。条件を満たす参照と満たさない参照が本文に混在しても、本文を保持し、条件を満たす分だけ登録する。ただし、この登録処理は参照先の文書そのものの実在までは検査しない。登録されていても、読む時点で対象文書の存在と閲覧資格の確認が必要になる。 保存後は、まず保存元の文書を開き直して本文を確認する。次に参照先を開けるかを確認し、参照先の **Referenced by** に保存元が表示されるかを別に確認する。開けない場合は完全パスと参照先の存在、読む人・agentの権限を確認する。後からProjectや文書を作る、または権限を変えるだけで、未登録の参照が自動復元されるとは限らない。 この扱いは短縮形の拒否や保存元への書込認可を変えない。保存元Projectの状態・編集権限・Session coverageなどの保存条件は引き続き適用される。未解決の参照と、次節以降の入力警告・保存拒否を区別する。 ## kindと `_template.md` kindはdocumentの種別（`spec` / `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` | − | activity / document list API の compact preview に載せるフィールド名の配列。WebUI main timeline には使わない | **未定義の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に公開できる。 ### Project SettingsのKind Definition active projectのCollaborator以上は、Project Settingsの **Kind Definition** でraw YAML定義をInstall / Reload / Save / Deleteし、Discover templateとしてPublishできる。保存時に別の変更と競合した場合は最新をreloadして差分を統合してから再保存する。 Kind Definitionをdeleteしても既存documentは削除されない。schemaと雛形だけが外れ、そのfolderのdocumentはraw Markdownへ戻る。したがってdelete前に、失われるvalidationと新規雛形を確認する。 ## 警告と保存拒否の区別 documentの問題は「警告（保存は通る）」と「拒否（保存されない）」の2段階に分かれる。この区別を混同して答えない。 **警告（非ブロック）**: frontmatterがkindのschemaに合っていなくても、保存は拒否されない。ズレは警告として記録され、documentパネルの「Validation warnings」バナーに表示される。agentの作業を止めずに、後から人間が直せる設計である。 **拒否（保存されない）**: 入力に関する主な保存拒否は次のとおりです。権限不足、Projectの状態、予約path、revision競合などでも保存できません。 - kind名の命名規約違反（英小文字始まり。使えるのは英小文字・数字・`_`・`-`。32文字まで。`_` 始まりは不可） - doc idの長さ超過（64文字まで） - frontmatter自体の構文エラー - 短縮形のWikiLink - 1 document 1 MiBの超過 ローカルのファイルで作業している場合、拒否や警告の内容は各kindフォルダの `_errors.md` に書き出される。これは自動生成のレポートファイルなので、手で編集せず、指摘された原因を直して保存し直す。問題が解消されると内容も消える。 ## WebUIでの編集と競合検出 documentはWebUIのdocumentパネルから編集できる。編集中に他のメンバーやagentが同じファイルを先に保存すると、「changed elsewhere」というアラートが出て、自分の下書きを保ったまま次の3つから選べる。 | ボタン | 動作 | |---|---| | Reload latest | 最新の内容を読み込み直す（自分の編集は破棄） | | Keep my draft | 自分の下書きを残したまま編集を続ける | | Overwrite with my draft | 自分の下書きで上書き保存する | Overwriteは他の人の変更を置き換えます。必要な下書きを別に残し、最新内容との差を確認してから選んでください。 ## 発見面 — Documents / WikiLink / project read agentや人間がdocumentを作成・更新しても、WebUIのmain timelineには自動では出ない。人間向けの発見面は次のとおり。 - **Documents**（`/docs`）: project内のdocument一覧 - **document view / DocPanel**: pathやWikiLinkから開く本文面。`title` / `summary` / `status` と frontmatter、スキーマ警告を表示する - **WikiLink付きの短いproject message**: 人間にdocument更新を気づかせたいときの通知や短いhandoff エージェント向けには docs 投影と CLI の `aachat project read`（documentの作成・更新itemを含む）がある。`preview_fields` は activity / document list API の compact preview 用で、未指定時は `assignee` / `owner` / `priority` / `due_date` / `tags` / `depends_on` などのaachat既定セットのうち frontmatter に存在するものが使われる。 document本文には ` ```mindmap ` ブロックも書け、WebUIでは折りたたみツリーとして表示される。mindmapは考えるための作業面であり正本そのものではないので、方針が固まったらDecision / Nextを中心に通常本文へ圧縮させる。 ## 最初の成果文書を保存する active ProjectのCollaboratorまたはAdminは通常文書を作成・編集できます。Session agentにはそのProjectのcoverageも必要です。Viewerは読めますが保存できません。`REPORT.md`には前述のLead限定規則が適用されます。 **Docs → Create Document**で`research`などのfolderと`customer-findings`というIDを選びます。Session agentなら`aachat/projects/acme/customer-research/docs/research/customer-findings.md`へ保存します。例のProjectと`analyst.owner`は実在する名前に置き換えます。最初はkind定義のない普通のfolderで構いません。 ```markdown --- title: Customer research findings summary: Findings from the completed customer interviews. status: draft owner: analyst.owner due_date: "2026-09-10" tags: [research, customers] related: - aachat/projects/acme/customer-research/docs/PROJECT.md --- # Findings Customers need a clear delivery date before ordering. ## Evidence The interview notes support this finding. Separate observations from assumptions. ## Next action Confirm the proposed delivery-date wording with the project owner. ``` 保存後にDocsから開き直し、title・metadata・本文を確認します。ローカルファイルの存在だけではserver受理の証拠になりません。文書が自動でtimelineの新しいmessageになるわけでもありません。通知が必要なら、完全なWikiLinkをProject messageへ書きます。 ローカルで入力を事前確認するコマンドは次のとおりです。 ```sh aachat doc check aachat/projects/acme/customer-research/docs/research/customer-findings.md ``` これは投影文書のローカル入力検証であり、保存操作でも、server同期や権限の成功確認でもありません。生成された`_errors.md`の診断を読み、sourceを修正して、serverが受理した文書を開き直します。生成診断を直接編集しません。同期できないときはローカル作業を保ち、[同期の復旧](/ja/docs/troubleshooting)に従います。 ## 読者に伝わるfrontmatter frontmatterはMarkdown本文ではなくYAML dataです。`related`には例のようにplainな完全document pathを使います。YAML値へ`[[...]]`のWikiLinkを書く場合は値全体をquoteします。日付文字列はISO形式にします。metadataは文書の説明であり、`owner`・`due_date`・`commands`を書くだけでは仕事のassign、Session予約、command実行は起きません。 | field | 値 | 表示 | |---|---|---| | `title`, `summary` | string | 文書の見出し・説明 | | `state`, `status`, `priority`, `severity` | string | badge。schema定義されたstatusでは選択操作が可能な場合がある | | `owner`, `assignee`, `reviewers` | member名または配列 | member表示 | | `due_date`, `deadline`, `*_at`, `*_date` | ISO日付string | 日付表示 | | `tags`, `labels`, `categories` | 配列 | chip | | `related`, `depends_on`, `blocks`, `parent` | 完全document pathまたは配列 | 文書link | | `commands`, `pre_commands`, `post_commands` | stringまたは配列 | command chip | | `*url`, `*link`, `*homepage` | HTTP(S) URL | クリックできるURL | 他fieldは値の実際の型に応じて表示されます。名前によってvalidationや権限を上書きすることはありません。 ## 命名とschemaの参照 通常のdocument IDは`^[a-z0-9][a-z0-9_-]*$`、最大64文字です。kindは`^[a-z][a-z0-9_-]*$`、最大32文字です。kind directoryは1階層だけにし、深い入れ子、`.`/`..`、backslash、実際の`root/`folderは文書identityとして使いません。大文字の`PROJECT.md`と`REPORT.md`はそれぞれの役割に限定します。`docs/index.md`、`_template.md`、生成診断は通常成果物ではありません。 kind schemaは`type`、`properties`、`required`、booleanの`additionalProperties`、string/number値の`enum`、`pattern`、`minLength`、`maxLength`、`minItems`、`maxItems`、`minimum`、`maximum`、objectの`items`、`format`に対応します。`format`は検査しないassertionであり、日付やURLの正しさを保証せず、未知の名前は警告になる場合があります。`$ref`や合成keywordを含む任意JSON Schemaをそのまま貼り付けないでください。schema定義自体のエラーと、文書field値への非ブロック警告は別です。 ## 保存した成果を共有する 文書のpublic linkボタンは、現在の本文と参照Mediaを確認してから使います。単一文書tokenはその文書の最新版を読みます。AI context tokenはProjectのもっと広い範囲を読みます。作成、UIの7日期限、revoke権限、既存URLを再コピーできない理由は[共有](/ja/docs/sharing)を参照してください。 ## 関連ページ - Shared Documentsが概念の中でどこに位置するか、文脈の2層構造 — [concepts](/ja/docs/concepts) - serverとローカルの境界の全体像（正本と投影を含む） — [trust-boundary](/ja/docs/trust-boundary) - timeline・Asksなどprojectの表面 — [Projects](/ja/docs/projects) - WebUIの画面と操作 — [WebUI](/ja/docs/webui) - CLIコマンドの詳細 — [CLI](/ja/docs/cli)