rtfreporter の開発は、いまではほとんどがチャットアシスタントを介して進んでいます。 この記事は、それをうまくやるための手引きです。コードを書かせる前に何を渡すのか、 どこまでは判断を信用してよく、どこからは信用してはいけないのかを扱います。
手で開発したい場合、ここに書かれていることはすべて任意です。末尾の アシスタントを使わない場合 まで読み飛ばしてください。
何が問題なのか
rtfreporter
は新しく、どのモデルの学習データにも入っていません。rtfreporter の
コードを求められたアシスタントは、自分が知っているパッケージ
— r2rtf — に
手を伸ばし、rtf_body()、rtf_colheader()、create_table()
を書きます。正しい
関数にたどり着いた場合でも、それらしい引数を発明します。
しかもそれらは「推測です」と明示されません。結果として、すべての名前をリファレンス と突き合わせて確認することになり、自分で書くより遅くなります。
手順 1 — 開発者マニュアルを添付する
ダウンロードして、セッションの最初に添付してください。
そのうえで、こう伝えます。
rtfreporter のコードベースを触るときは、このマニュアルに従ってください。
約 18 KB の自己完結した 1 ファイルです。おおよそ 5,000
トークンなので、長い会話と
並行してもセッションに無理なく収まります。中身は、不変条件、S3
オブジェクトモデル、
レンダリングパイプライン、as_rtftables() の kwargs
契約、テーブルオブジェクト アダプタの追加手順、コード / テスト /
ドキュメントの規約、ソースファイルマップ、
そして実際に踏み抜かれてきた罠です。
添付するのは 1 つだけ
もう 1 つ、パッケージを使って帳票を作る人向けの AI ユーザーマニュアル があります。両方を同時に添付しないでください。
両者は正反対の指示を持っています。ユーザーマニュアルの第一の規則は「公開 API だけを 使い、内部には触れるな」であり、開発者マニュアルはその逆を要求します。両方を渡すと、 アシスタントは自分で折り合いをつけようとして、どちらの規律も守らなくなります。
各ファイルの冒頭には、それがどちらなのかを宣言する行があります。添付したものが意図 したものかどうか、そこで確認できます。
手順 2 — 自分の権限レベルを伝える
このリポジトリへの push 権限があってもなくても、作業内容は同じです。違うのは git コマンドだけです。マニュアルはアシスタントにこう確認させます。
ただし、最初に自分から「fork で作業しています」「write 権限があります」と伝えたほうが 速く、ブランチと PR のコマンドが一度で正しく出ます。
手順 3 — issue を進める
ライフサイクルはマニュアルが既に知っているので、最初のプロンプトは短くて構いません。
issue #123 は X を求めています。マニュアルの 5 章を読んで、変更方針を提案してください。 コードはまだ書かないでください。
方針が固まってから、
実装してください。ブランチは
feat/123-slug。R/、テスト、roxygen をまとめて更新し、devtools::document()、devtools::test()、lintr::lint_package()を実行、NEWS.mdに追記し、Closes #123を入れて PR を作成してください。
この一覧はすべてマニュアルに書いてあります。それでも明示的に並べておくと手間がかからず、 レビュー時に抜けが目に付きやすくなります。
入っていないものに注目してください —
バージョンの引き上げです。R 標準のスキーム （リリースは
X.Y.Z、開発版は X.Y.Z.9000）のもとでは、通常の
PR は DESCRIPTION を
触りません。他が名前で参照する必要のある変更のときだけ第4要素を上げます。X.Y.Z
を 触れば release ラベルが無い限り
version-guard が落とします。“親切に”バージョンを
上げるアシスタントはリリースをしていることになり、CI
からそう告げられます。
信用してよいこと、自分で確認すべきこと
マニュアルを持ったアシスタントは、形については信頼できます。どの関数を呼ぶか、 その引数が何をするか、変更がどのファイルに属するか、テストが何を検証すべきか。これらは まさにマニュアルが運んでいる事実です。
一方、マニュアルに収めようがないことについては信頼できません。
-
RTF が実際にどう表示されるか。
パイプラインのどこにも、Word で開いたときに表が
正しく見えることを保証する仕組みはありません。列幅、改ページ、脚注が下余白に
ぶつかっていないか —
.rtfを開いて確認してください。 - 臨床的な正しさ。 分母、シフトテーブルのカテゴリ、脚注が SAP と一致しているかは 人間の判断です。ここで自信満々に間違われると、代償が最も大きくなります。
- そもそもその機能をパッケージに入れるべきか。 スコープの上限（不変条件 8）は 設計上の立場であって、機械的に検査できる規則ではありません。アシスタントは、 本来は断るべきものを喜んで実装します。
- API 設計。 引数名とデフォルト値は、ユーザーが最も長く付き合う部分です。人間が 決め、issue で議論する価値があります。
良い分担はこうです。変更とテストの草案はアシスタントに書かせ、自分の注意力は 出力された帳票と設計が正しいかに使う。
アシスタントが止まる場所
アシスタントは PR を作成します。マージはしません。
main は 7
つのグリーンなチェックに加えて承認レビュー 1
件を要求し、GitHub は
自己承認を認めません。したがってエージェントが単独で正当にマージを完了させることは
できません。マニュアルはそれを明記し、さらに、リポジトリオーナーがそのセッションで
指示しない限り管理者オーバーライドに手を出さないよう指示しています。
アシスタントは「PR を作成し、CI はグリーンです」と報告して待つはずです。その停止こそが レビューであり、それが狙いです。
マニュアルが陳腐化しない理由
古いマニュアルは、無いより悪いものです。アシスタントには区別がつかないからで、削除済みの 関数を、実在する関数とまったく同じ確信度で引用します。
そこで両マニュアルはテストで縛られており、乖離すると CI が落ちます。
- ユーザーマニュアルの関数一覧は
getNamespaceExports()と完全一致でなければ ならない（漏れも、実在しない名前も許さない） - deprecated なエクスポートはコードブロックに一切現れてはならず、かつすべての deprecated が deprecated として記載されていなければならない
- ユーザーマニュアルが教えるイディオムはすべて実際に実行される。エラーになると 書いてあるものも含めて
- 開発者マニュアルのソースファイルマップ、
Imports:一覧、S3 限定の主張は、 実際のツリーと突き合わせて検証される
実装は tests/testthat/test-ai-user-manual.R と
test-ai-dev-manual.R です。公開 API
を変更すると、これらのテストが「マニュアルも更新が必要だ」と教えてくれます。同じ
PR の中で更新してください。
アシスタントを使わない場合
ここまでの内容はすべて任意です。マニュアルは長文ドキュメントから圧縮して作った要約で あり、正典は長文ドキュメントのほうです。両者が食い違った場合は記事が正しく、 マニュアルがバグです。
次の順に読んでください。
- アーキテクチャと内部構造 — 全体像、オブジェクトモデル、 レンダリングパイプライン、リポジトリ構成。まずはここから。
- テーブルオブジェクトアダプタの追加 — 新しいテーブル パッケージに対応するための 6 ステップ。
- 内部クラス設計書（S3） — 設計の詳細ドキュメント。
-
CONTRIBUTING.md— コントリビューションの流れ、ブランチ、バージョニング、 リリース。Contributor / Collaborator の区別もここにあります。 -
AGENTS.md— 同じ内容を 1 ページに圧縮したもの。コーディングエージェント、 あるいは急いでいる新規コントリビューター向け。