3画面パック ⑦ コメント機能 — 要件定義¶
結論（3行）
- Wiki のページの下に「ひと言」を書ける欄を付けます。書くと Discord に飛び、右腕（社内で動かしている AI エージェント）が気づいて動きます。
- これは ⑥で「今日はやらない」と書いたものです。ページを置くだけでは付きません。小さな常駐サーバが1本要ります。
- 🔴 いちばん転ぶのは技術ではなく設定です。Discord は機械の発言を既定で捨てます。ここを開けないと、右腕は永久に起きません（→ 08の7節）。
📦 このパックの入口（ダウンロードはこちら） ｜ pmsw-pack.zip をそのまま落とす ｜ ⑧ 仕様書（作る人が読む）
この 07 は 「何のために作るのか」を決める紙です。作り方は 08_comment_spec に書いてあります。 右腕には 07 と 08 を両方読ませてください。07 だけだと作れず、08 だけだと目的からずれたものが出来ます。
1. 解こうとしている問題¶
いま、気づいたことは 2か所で消えています。
flowchart LR
R["ページを読む<br>（手順書・議事録・仕様）"] --> K["「ここ、もう古い」<br>と気づく"]
K -->|①| A["頭の中で終わる<br>（あとで言おう → 忘れる）"]
K -->|②| B["チャットに書く"]
B --> C["会話が流れて<br>どのページの話か分からなくなる"]
style A fill:#a33,color:#fff
style C fill:#a33,color:#fff| 消え方 | 何が起きているか |
|---|---|
| ① 頭の中で終わる | 読んでいる最中に気づく。でもその場に書く場所が無いので、別の道具（メモ帳・チャット）を開くところで止まる |
| ② 会話が流れる | チャットに書いても、どのページの何行目の話かが消える。数日後に読み返すと意味が取れない |
つまり、足りないのは「やる気」ではなく「置き場」です
気づいた場所に、そのまま書ける欄がある。それだけで、①も②も起きません。 書いたものはページに紐づいたまま残り、そのまま右腕への依頼になります。
2. 使う場面（3つ・具体的に）¶
場面 1 — 手順書を読んでいて、実物とズレているのを見つけた
社長が /standard/請求書の出し方/ を開いている。
「この振込先、去年変わったよな」と気づく。
- いま：別窓でチャットを開き、「請求書の手順書だけど、振込先が古い」と書く → どの手順書か右腕には分からない
- これから：そのページの 💬 を押し、「振込先が古い。2行目」と書いて送信 → ページのURL付きで Discord に飛ぶ → 右腕がそのページを開いて直す
場面 2 — 右腕が作った資料を、その場で差し戻す
右腕が作った提案書のページを読んでいる。8割は良いが、1枚足りない。
- いま：どこが良くてどこが足りないかを、記憶を頼りにチャットで書き直す
- これから：読みながら 💬 に「> 期待効果 この節の根拠になる表をもう1枚足して」と書いて送信 → 引用と一緒に届く → 右腕が続きから直す
場面 3 — 移動中にスマホで読んでいて、思いついた
スマホで Wiki を読んでいて、「この工程、型を作っておいたほうがいい」と思う。
- いま：スマホからチャットに長文を打つのは面倒なので、やらない
- これから：💬 に1行だけ書いて送信。送り先は事務所の右腕。読むのを中断せずに、ひと言だけ置いていける
3. やること¶
| # | やること | ひと言で |
|---|---|---|
| 1 | どのページにも 💬 ボタンを出す | ページを離れずに書ける。ログイン不要 |
| 2 | 書きかけを、打つそばから残す | 閉じても消えない。読み続けられる |
| 3 | 送信すると、サーバに記録が残る | 1件1行の追記だけ。消えない・上書きされない |
| 4 | 同時に Discord へ流す | 右腕がそこで気づく |
| 5 | 履歴が読める | 送ったもの・いまの状態（未対応／対応中／完了）が並ぶ |
| 6 | 状態を変えられる（右腕が） | コメント本体は書き換えない。状態も追記で表す |
4. やらないこと（スコープ外）¶
ここを広げると、必ず途中で止まります
最小構成は 「ページの下に欄がある。書くと Discord に飛ぶ。右腕が気づく」だけです。
| やらないこと | なぜ |
|---|---|
| 文章を選択して、その箇所に紐づける | 本文に > を付けて自分で引用すれば足ります。不便になってから足す |
| 返信のやり取り（スレッド） | 1往復で足ります。続きは Discord で話せばよい |
| ログイン・利用者ごとの権限 | 読む人が数名で、社内網（または Tailscale）の中だけだから |
| 送信したコメントの編集・削除 | 記録が信用できなくなります。状態を変えるだけにします |
| 書きかけを端末間で同期する | 書きかけはその端末のブラウザに置きます。送信すればサーバに残ります |
| メール通知・外部サービス | 入口は Discord 1本。増やすほど誰も見なくなります |
5. 落とした機能と、その理由¶
これは「後から足すときの判断基準」です
元になった実装には、今回入れない機能が入っています。落とした理由を残しておくと、 後で「やっぱり要る」となったときに、何を足すのかが1行で分かります。
| 落とした機能 | 元の実装で何をしていたか | 落とした理由 |
|---|---|---|
| 複数サイトをまとめる入口 | 16個の Wiki を1枚に並べる | サイトが1つなので、まとめる相手が居ない |
| シェルフの並び替え（棚を6つに分けて出し入れ） | 棚ごとに wiki を移動できた | 棚に入れるものが無い。⑥で作る6つの棚で足りる |
| 記事の既読・スター管理 | 読んだ / 気になる を端末をまたいで保存 | 読む人が数名。既読を管理するほどページが無い |
| 送り先の自動一覧（動いている会話スレッドを並べる） | 社内の別システムの API を叩いて、生きている会話を毎回取ってくる | その API に依存します。無い環境では動きません。送り先は手で登録した1〜数本で足ります |
| 送り先の親チャンネル学習・総当たり | どの通知口がどの会話につながるか、試して覚える | 上を落とすので、当てる相手が居ません |
| 添付ファイル付きのメモ送信窓 | 画像やファイルを Discord へ投げる別画面 | 別の機能です。コメントと混ぜると、どちらも説明できなくなります |
| ページの原稿（Markdown）ダウンロード | 読んでいるページを .md で落とす | 別の機能。今回の問題（気づきが消える）を解きません |
| サーバ稼働状況のモニター画面 | 機械の状態を1枚にまとめる | 今回の目的と無関係 |
| パネルの移動・拡大縮小 | 吹き出しをドラッグして好きな位置・大きさに | あると快適ですが、無くても書けます。作る量が倍近くになります |
| 溜まったコメントを捌くコマンド | 未対応を一覧して状態を変える小道具 | 最初は件数が少ないので、API を1回叩けば足ります（→ 08の5節） |
6. 前提（この環境で作ります）¶
| 機械 | Ubuntu のミニPC 1台 |
| サイト | MkDocs + Material（すでに動いているもの） |
| 常駐のさせ方 | pm2（すでに他のものを動かしているなら、同じ並びに足す） |
| 通知の入口 | Discord（Bot 導入済み） |
| 読む人 | 経営者ひとり ＋ 数名。社内網または Tailscale の中だけ。インターネットには出しません |
| 作る人 | 右腕（Claude Code） |
7. 決めておくこと（作り始める前に、あなたが決めます）¶
| 決めること | 例 | 決まったら |
|---|---|---|
| コメントが飛ぶ先のチャンネル | #右腕 のような、コメント専用の1本 |
🔴 既存の監視通知のチャンネルは使い回さないでください（→ 08の7節） |
| 通知口（Webhook）を1本作る | そのチャンネルの設定から作る | URL を控える。チャットに貼らないこと（→ 08の6節の渡し方） |
| データの置き場 | /home/<あなた>/wiki-data/ のような、サイトの外 |
🔴 サイトの中に置くと作り直すたびに消えます（→ 08の4節） |
終わりの印：この3つが紙に書けている。
8. 受入条件 — 「出来た」と言える条件¶
🔴 「動きました」「エラーは出ませんでした」は、出来たことの証拠になりません
下の9つはすべて機械で判定できます。右腕には、実行した出力そのものを見せてもらってください。
| # | 条件 | どう判定するか |
|---|---|---|
| A1 | コメントを送信できる | 送信すると 200 と id（c で始まる文字列）が返る。記録ファイルが1行増える |
| A2 | 同時に書いても消えない | 25件を同時に送信 → 25件すべて読み出せる（欠け0件） |
| A3 | 状態を変えても本文が書き換わらない | 状態変更の前後でファイルを比べ、元の行がそのまま先頭に残っている／ファイルが1行だけ増えている |
| A4 | サイトを作り直しても記録が消えない | mkdocs build を1回実行 → 記録ファイルがそのまま在る（行数が変わらない） |
| A5 | Discord が落ちていても記録は残る | 通知先を止めて送信 → 200 かつ notified: false が返り、記録は増えている |
| A6 | 通知口の URL がブラウザに出ない | 送り先一覧の応答を文字列として検索し、http も webhook も1文字も含まれない |
| A7 | おかしな入力を弾く（陰性対照） | 空・長すぎ・ページ指定がおかしい・知らない状態名 → 4つとも 400 |
| A8 | 実際に Discord に届く | 1本送って、チャンネルに本文の引用と元ページの URL が出る。送信元の名乗りが Python-urllib でない（既定のままだと Discord に弾かれます） |
| A9 | 右腕が自分から起き上がる | コメントを1本送る → 誰も話しかけていないのに右腕が動き出す（→ 08の7節） |
A9 だけは、設定を1つ開けないと通りません
A1〜A8 が全部通っていても、A9 は通らないことがあります。そこで諦めないでください。 プログラムの問題ではなく、Discord 側の設定です。切り分けは 08の7節 に3手で書いてあります。
終わりの印：A1〜A9 の実行結果が、出力そのもので9つ並んでいる。
9. この機能が「使われている」と言える状態¶
作り終えることと、使われることは別です。使われているかどうかは、この3つで分かります。
| 見るところ | 成功している姿 |
|---|---|
| 記録ファイルの行数 | 増え続けている（週に数件でよい） |
| 状態 | 未対応が溜まりっぱなしになっていない |
| チャットの中身 | 「あの手順書のどこだっけ」という探す会話が減っている |
次は 08_comment_spec（仕様書・作る人が読む） です。