Markdownの表示と構造化ブロック

aachatのMarkdownには、Mermaidに加えて3つの構造化fenced blockがある。mindmap（思考の整理）、brainstorm（案の発散）、task（実行依頼の分解）である。chatメッセージにも共有ドキュメント本文にも書け、WebUIがインタラクティブなカードとして描画する。

3つに共通する事実:

• 表示は読み取り専用である。折りたたみ・並べ替え・コピーはできるが、UIから内容（status・rating等）を変更する操作はない。更新はMarkdown本文の編集で行う
• ブロックを書いても何も自動実行されない。taskブロックのstatusを変えてもsessionは起動しない
• 構文エラーがあるとブロック全体がエラー表示（行番号付き）になり、元のテキストがそのまま表示される
• どれも思考・調整のための作業面であり、正本ではない。固まった結論は通常の文書・依頼文に圧縮する

書く前に — 表示と実行を分ける

文章、表、図、成果物への参照を同じ本文にまとめ、読者が内容を確認できるようにするためのガイドである。chatへ投稿できる人・agent、または対象の共有ドキュメントを編集できる人・agentがMarkdownを書く。閲覧できることと、本文を変更できることは別の権限である。文書の保存・編集条件は共有ドキュメント、媒体の準備はProject Mediaを参照する。

コード、Mermaid、構造化ブロックを表示しても、その内容をコマンドとして実行せず、Sessionの起動や担当agentへの委任も行わない。 [Agent] は担当の記述であり、権限の付与ではない。チェックボックス、rating、statusは本文に書いた値の表示である。実行する仕事は別途Sessionへの依頼として渡す。

ただし、表示には図の描画や認証済みMediaの取得が伴う。リンクを開く操作も外部へのアクセスになりうる。「自動実行しない」は通信が一切ないという意味ではない。生のHTMLを貼っても、このMarkdown表示面で任意のHTML・scriptを実行する用途にはならない。HTML成果物は別のProject HTMLの実行・共有条件に従う。

表示と読取専用操作の対応表

ここでのchatはWebUIのメッセージ本文、共有文書はWebUIのMarkdownプレビューを指す。下の3ブロックの例では、外側の4個のバッククォートはガイドで構文を見せるための囲いである。利用時には内側の3個のバッククォートから閉じる3個までを本文へコピーする。例中の数値・計画・agent名は説明用であり、測定結果や実在する担当の保証ではない。

chatと公開ガイドは本文の単一改行も改行として表示する。共有文書のプレビューでは単一改行は通常Markdownの段落内改行として扱う。段落を分けたいときは空行を入れ、確実な強制改行が必要なときは行末に半角スペース2個を置く。

通常Markdown・code・Mermaidの例

次を本文に貼ると、見出し、強調、引用、未完了・完了の表示、2列の表、ガイドへのリンクが表示される。

## 確認メモ
**結論**と *仮説* を分ける。~~古い案~~ は取り消す。

> 共有前に参照先を確認する。

- [ ] 図を確認する
- [x] 本文を読む

| 対象 | 状態 |
|---|---|
| 原稿 | 確認中 |

[共有ドキュメントのガイド](/ja/docs/shared-documents)

次のコードは文字列として表示され、helloを出力するための実行は行われない。実行したい場合だけ、別の環境で内容を確認して実行する。

```javascript
console.log("hello");
```

次のMermaidは「原稿 → 確認 → 共有」の3ノードの図になる。これは作業手順の説明であり、共有操作を実行しない。

```mermaid
flowchart LR
  A["原稿"] --> B["確認 (review)"] --> C["共有"]
```

Mermaidはstrict設定で描画される。図内のHTMLやクリックによるスクリプト実行を前提にしない。

画像・動画・PDF・WikiLinkの例

先にMediaを保存して、Media一覧から実際のcanonical URLを取得する。以下のUUIDは例なので、それぞれ自分の画像・動画・PDFのUUIDへ置き換える。短命な配信URLやローカルファイルの絶対パスは保存しない。

![完成画面](https://aachat.work/m/11111111-1111-4111-8111-111111111111)
[操作動画](https://aachat.work/m/22222222-2222-4222-8222-222222222222)
[報告書PDF](https://aachat.work/m/33333333-3333-4333-8333-333333333333)

[[aachat/projects/example/demo/docs/notes/review.md]]

WikiLinkも、自分が参照する文書の完全パスへ置き換える。本文に書くと文書チップになるが、このガイドのコード例内では文字列として表示される。チップを作るためにファイルを新規作成したり、他Projectへのアクセス権を付与したりすることはない。

公開ガイド・共有先での見え方

公開ガイドのMarkdown表示は原稿を読む経路であり、Projectを共有する機能ではない。共有リンクでも文書本文を編集したりTaskを開始したりするUIは付かない。外部のMarkdownツールへ渡した場合の図・HTML・リンクの扱いはそのツールに依存するので、必要な結論を普通の本文にも残す。

canonical Media URLを貼るだけでは、非メンバーに閲覧権限を渡せない。共有Markdownは有効な共有tokenとその範囲でアクセスを判定し、リンク先文書やMediaすべてを無条件に公開するものではない。外部画像参照をリンクやテキストにする経路もある。期待した画像や文書が開けなければ、本文の参照、Mediaの存在、共有範囲、期限・失効を作成者が確認する。共有の扱いは共有ドキュメントとProject Media、別のHTML成果物の公開はProject HTMLを参照する。

mindmap — 論点の構造を整理する

- [タグ] テキスト をスペースのインデントで木構造にして書く。複雑な仕様・調査・判断を、FactとAssumptionを区別しながら整理するのに使う。

```mindmap
title: 検索改善の判断
- [Goal] 検索の初回体験を良くする
  - [Question] 遅いのはどこか？
    - [Fact] p95は800ms、インデックスは未使用
    - [Assumption] ユーザーは300ms超で離脱する
    - [Option] インデックスを追加する
      - [Risk] 書き込みが遅くなる
    - [Decision] インデックス追加を先に検証する
      - [Next] ベンチマークをとる
```

• タグは12種: Goal Question Fact Assumption Concept Cause Option Tradeoff Risk Test Decision Next。未知のタグは警告付きでそのまま表示される
• title: 行は任意で、最初のリスト項目より前に1つだけ置ける
• インデントはスペースのみ（タブはエラー）。リストマーカーは - を使う。最大200ノード
• 表示は意味タグごとに色分けされた折りたたみツリー。ホバーで祖先パスがハイライトされる

brainstorm — 案を並べて評価する

question / background / ideas をYAML風に書く。仕様・UX・改善案の候補を発散し、人間に評価してもらう場面で使う。

```brainstorm
question: オンボーディングの離脱をどう減らすか？
background: |
  初回セットアップの完了率は60%。落ちるのはagent作成の手前。
ideas:
  - title: テンプレートagentを1clickで作る
    description: |
      名前入力だけでDiscoverの定番agentを複製する。
    rating: 4
  - title: セットアップをWebUIだけで完結させる
    description: CLIインストールを後回しにできる導線にする。
```

• ルートキーは question（必須）/ background(任意) / ideas（必須）の3つだけ。ideaのキーは title（必須・50文字以内）/ description（必須・200文字以内）/ rating（任意・1〜5の整数）だけ
• background とideaの description は | の複数行が書ける（description全体で200 Unicodeコードポイント以内）。question と title は単一行。ネスト・アンカー等のYAML機能は使えない。最大100案
• 表示はアイデアカードのグリッドで、ratingは n/5 バッジ。ratingをUIから付ける・変える機能はない。評価を反映するにはMarkdown本文の rating: を編集する（並べ替えのSort切替は表示のみ）
• 重要な決定はbrainstormのまま放置せず、Ask（projects）や仕様の文書に圧縮する

task — 実行依頼に分解する

大きなGoalを、担当agent・status・期待Outputが見える実行依頼に分解する。委任（sessions）やチーム内の分担の設計図として使う。

```task
title: docs改善の分担
- [Goal] 未記載機能の質問にdocsだけで答えられる
  - [Task] 現行docsのカバレッジを監査する
    - [Agent] @researcher
    - [Status] doing
    - [Question] どの質問にどのページが答えるか
    - [Output] 質問ごとの穴の一覧（ページ・行付き）
    - [Hint] 質問はユーザーの実際の言い方のまま扱う
```

• タグは7種のみ: Goal Task Agent Status Question Output Hint。未知のタグはエラー（mindmapより厳格）
• ルートは [Goal]。各 [Task] の直下には [Agent] → [Status] → [Question] をこの順で必ず置き、[Output] を1つ以上書く。[Hint] は任意、[Task] のネストで子タスクを作れる
• [Agent] は @agent名 または unassigned。[Status] は todo / doing / blocked / done の4値（不正な値は警告付きで todo 扱い）
• リストマーカーは - のみ（* や + はエラー）。タブ不可。最大100タスク、全タグ合計200ノード
• 表示はstatus別の集計付きタスク一覧。statusの更新はMarkdown本文の編集で行い、UIのクリックでは変わらない。taskブロックはproject boardではないので、期限・優先度・進捗%のフィールドはない
• PROJECT.mdには置かない。可変の実行計画が必要なら別のShared Documentに、現在または次に実行可能なTaskだけを書く
• agentにtaskを実行させるには、ブロックを書くだけでなく通常どおり依頼を出す（宛先指定の依頼、またはagent間の委任）。[Task] の本文がそのままsessionへの依頼文になる粒度で書く

ブロックを修正して再表示する

エラー表示の行番号をブロック内の元テキストと照合し、本文を編集して保存・再表示する。閉じるfenceが欠けていないか、タブや未知キーがないか、taskの必須項目と順序が揃っているかを確認する。長い説明はブロックの外の本文へ移す。タイトルや項目内には強調やリンクなどのinline Markdownを使えるが、見出し・引用・リスト・別のfenceなどのblock Markdownは入れない。警告付きで描画できても、statusの代替表示やタグの誤記を成果確認と取り違えず、原文を直す。編集権限がない読者は作成者へ修正を依頼する。

関連ページ

• 委任と複数agentの協働の実務 — sessions
• timelineの描画とWikiLink — projects
• 共有ドキュメントの契約（ブロックを文書に書く場合） — shared-documents