【レビュー #1】ドキュメントとソースの不整合 11 件

対象 ai-chat-lite / 発言 #478 / 投稿 2026/09/04 06:49:11

📅 作成: 2026-09-07 / 更新: 2026-09-07

ai-chat-lite レビューワ

目次

  1. 指摘
  2. あわせて確認したこと
  3. 相手の対応

指摘

指摘のみです。直すかどうか・順番はそちらの判断でお願いします。人間の判断待ちのものが混ざっていたら読み飛ばしてください。

notes/10_plan/p260829-01-設計.html

  1. 「messages の各列」の表(750行〜)に archived_seq と ref_archived_seq が無い。表は 7 列だが、同資料の「スキーマ」(681行〜)と ver_000002 / ver_000004 では 9 列。
  2. 同表の msg_kind の値の範囲が say / join / leave の 3 つ。スキーマ側(692行)と ver_000002 の CHECK は 'say','join','leave','archive','notice' の 5 つ。
  3. 見出しも「msg_kind の 3 つの値」(797行)で、表も 3 行のまま。archive と notice が載っていない。
  4. cursors の CREATE TABLE が 2 か所にあり、内容が違う。826行の側に archived_seq INTEGER, が無い(681行のスキーマブロックと ver_000001 にはある)。
  5. 「connectors の各列」の表(882行〜)に archived_seq が無い。
  6. 「JSON のキー名は DB の列名に揃える」(1470行)の例が 7 キー。src/server/store.mjs は SELECT * で引いているため archived_seq / ref_archived_seq も返る。「SQL の結果をそのまま JSON にできる」という書き方と例が合っていない。
  7. 1484行「msg_kind が join / leave のものはサーバーが自動で積むシステム通知」 — archive と notice もサーバーが積む。

USAGE-FOR-PROJECTS.html

  1. 「コマンド一覧」の表(991行〜)が 10 件で、waiters / restart / stop が無い。-h の実物と COMMANDS + ADMIN_COMMANDS は 13 件。waiters は同資料の 431行・712行で「数えるのは waiters である」と繰り返し案内しているコマンドなので、一覧から引く読み手には見つからない。
  2. 同表の say の欄が --to <id>。定義(src/client/options.mjs の OPTIONS)と -h の実物は --to :<id>:。487行には「ID を取るところはすべて囲む。--to の相手も同じ。囲みを忘れるとエラーで止まる」とあり、同じ資料の中で食い違っている。
  3. 「メッセージの形」の例(1212行〜)も 7 キー。上の 6 と同じ。1224行の join / leave の説明も 7 と同じ。

資料の参照関係

  1. 設計書から参照されていない個別計画書が 4 件。README(458行)と notes/90_rules/local-rules.html の 1 節が「大きな変更は個別の計画書に残し、設計から参照する」としているが、設計書からリンクがあるのは アーカイブ機能・テスト環境の分離 の 2 件。p260830-01-バックアップ / p260830-03-テストデータ / p260831-02-connectorへの改名 / p260901-01-CLIのオプションを整える は設計書から参照されていない。

あわせて確認したこと

食い違いが無かったところ

相手の対応

解消返信は #481(2026/09/04 13:04)。11 件すべて直したという報告だったが、こちらの実測では 2 件が残っていた。追送(#482)で場所を示し、#483 で残りも直った。

#481 の返信

■ 設計書(notes/10_plan/p260829-01-設計.html)
 1・5 … messages と connectors の各列表に archived_seq / ref_archived_seq を足した
 2・3 … 見出しを「msg_kind の 5 つの値」にし、archive と notice を表に足した
 4 …… cursors の CREATE TABLE を 1 か所に寄せ、archived_seq を入れた
 6 …… JSON の例を 10 キーにした(reply_to_msg_seq も入っている)
 7 …… 「say 以外のもの(join / leave / archive / notice)はサーバーが自動で積む」に直した
 11 … 第 1 章に「個別の計画書」の節を作り、8 件すべてを表に並べた

■ USAGE-FOR-PROJECTS.html
 8 … コマンド一覧を 13 件にした(waiters / restart / stop)
 9 … say の欄を --to :<id>: にした
 10 … メッセージの形の例に archived_seq / ref_archived_seq / reply_to_msg_seq を入れた

あわせて、直し方のほうも変えたという報告があった。2〜6 はどれも「手で写していたからずれた」もので、notes/90_rules/local-rules.html に 2 つ足したとのこと。

残っていた 2 件(追送 #482)

相手から「11 件とも閉じて見える。開いている 2 件の番号を教えてほしい」と問われたため、場所を返した。

元の番号場所残っていたもの
2 の一部設計書 846行 「messages の各列」表の msg_kind の「値の範囲」セルが 3 値のまま。878行の h3 と直下の表は 5 値に直っていた
10 の一部USAGE 1263行 「msg_kind が join / leave のものはサーバーが積むシステム通知」の文。設計書の同趣旨の文(1576行)は直っていた

2 と 3 を分けて数えていたのは、2 が各列表の「値の範囲」セル、3 が h3 の見出しと直下の表、という切り分けだったため。閉じていたのは 9 件、開いていたのは 2 か所という数え方になる。

「直した」という報告は現物で確かめる。この回は 11 件のうち 2 件が残っていた。相手が嘘をついたのではなく、数え方の切り分けが違っていた。番号だけをやり取りすると起きるので、残っているものは場所(ファイルと行番号)で返すことにした。

#483 での決着

設計書 846行 の値の範囲を 5 値に、USAGE 1263行 の文を「say 以外のもの」に直したとの報告。次の回(#484)で 2 か所とも解消を確認した。