業務システムの内部APIを開発者ツールで洗い出し、JSON Schemaに移す
業務システムの内部APIを開発者ツールで洗い出し、JSON Schemaに移す
前日の夕方に「明日やること3本立て」を進捗メモへ書き残しておいた。 それなのに翌日には、何を残したのかが自分の口から出てこない。 そこで最初に、そのメモから前日の積み残しを一覧にしてもらった。
出てきたのは3本立てと、細かい積み残しのリストだった。 この日やるのは、ある支援先の業務システムを開発者ツールで一周し、画面と通信から仕様を読み取る作業である。 読み取りだけで進む3段があり、そのあとに実際に1件登録してみる一周テストが控えていた。
対象は支援先の実データが入っている環境なので、触ってよい条件を先に決めてある。 平日の業務時間内であること。 その日は水曜の14時で、条件は満たしていた。
ドキュメントが食い違ったときの決め手
先に手をつけたのは、登録項目のうち意味の割れている1項目だった。 手元の内部ドキュメントが2本あって、一方はその項目を区分コードだと書き、もう一方は事業者を識別するコードだと書いている。 どちらが正しいか分からないままでは、登録の自動化が先へ進まない。
一覧から1件開いて、読み取り専用の照会画面を出した。 項目のラベルに区分名がそのまま表示されていた。 念のため同じレコードの修正画面でフォームの中身を並べたら、その項目は選択肢2つのセレクトで、値と表示の対応まで取れた。 区分コードだと書いていた側が正しく、もう一方が誤りだった。
このとき決めていたのは、削除に当たる処理には触らないことである。 一覧の行には引数違いで挙動が変わる関数がぶら下がっていて、引数のひとつが削除に相当していた。 どのボタンが何を呼ぶのかを先に読んでから押した。 結果として、更新を1度も走らせずにフォームの56項目を列挙でき、登録に必要な36項目まで確定した。
読み取りだけでは出てこない通信
読み取りで分かったつもりになっていても、登録のリクエストは実際に押さないと出てこない。 テスト用のレコードを1件作ることにした。
コード欄に値を入れた瞬間、事業者名が自動で表示され、区分と業種も勝手に埋まった。 裏で別フレームを経由して内部APIを1本叩いている作りだった。 分類は大中小の3階層で、上を選ばないと下の選択肢がサーバから降りてこない。 1段ずつ選びながら、選択肢を取ってくる内部APIを2本見つけた。
更新を押したあと、一覧の1行目に自分が入れた行が並んでいるのを画面で確認した。 このテストレコードは、確認を終えたあとで消した。
通信ログを開いたところで、報告しておくべきことが1つ出た。 ログインのPOSTに認証情報が平文で乗っている。 こちらで作りを変えられる話ではない。 採取した応答ファイルを消し、ドキュメントにも書かず、事実だけを共有した。
テキストで書いた仕様が抱えていた弱さ
ここまでの成果は、マークダウンのファイルに直接書き足させていた。 書き足していくうちに引っかかった。 API仕様を書いているのに、テキストへの直打ちでいいのか。
テキストで書いた仕様は追記のたびに壊れる。 項目が1つ増えたときに書き忘れても、誰も教えてくれない。 そこで仕様の正本をJSONに移し、JSON Schemaを添えた。 検証を走らせたら1件だけ落ちたので、スキーマ側を直して通した。 以後の追記で壊れたときに気づけるよう、検証スクリプトも一緒に置いた。
分類マスタも同じ考え方で先に片づけた。 3階層の選択肢は上を選ばないと下が降りてこないので、そのつど実機を叩くことになる。 それでは面談のたびにシステムへログインしなければならない。 9つある大分類を1つずつたどり、中分類66件と小分類167件を採取してJSONに入れた。 選択肢を出すために実機へ触る必要は、これでなくなった。
面談の音声から登録までを1本のスキルにする
次にやりたかったのは、面談の音声の文字起こしを渡して議事録を作らせ、そのまま登録まで通すことだった。 このとき分類を勝手に決めさせるつもりはない。 中身を読んだうえで根拠つきの推奨を出させ、こちらが確認してから確定させる。 その手順をそのままスキルにまとめ、API仕様のJSONをリファレンスとして参照させる形にした。
作ったスキルを使って、その日の午前にあった面談の文字起こしから議事録を作り、登録まで通した。 途中で1度、同じ質問を繰り返したように見えた場面がある。 実際には大分類を変えたことで中分類の一覧が丸ごと入れ替わっていて、前に選んだ選択肢はもう存在していなかった。 説明はついたものの、聞かれる側からは区別がつかない。 判断は最後に1回でまとめて聞く、とスキルに書き足した。
業務上のルールも、その場で伝えて書き足させた。 特定の計画を作るときだけ使う区分があり、それ以外は一般の区分を使う。 知らなければ毎回間違える種類の知識で、こういうものはスキルに残さないと次の日には消える。
議事録の保存先だけは決められなかった。 支援先の環境のどこへ置くかは、支援先の手元でしか決まらない。 設定ファイルを1つ作り、READMEの目立つ位置に「未設定事項」として書いて渡した。
共有リポジトリへ出す前の伏せ字
作ったスキルは支援先と共有するリポジトリへ入れる。 push前に中身を走査したら、ログインIDが7箇所そのまま書かれていた。 プレースホルダに置き換え、事業者名が紛れていないかも確かめてからコミットした。
ここで削除ガードが1度止まった。 コピー先を作り直そうとして、変数を展開したパスへの再帰削除が拒否された。 初回のコピーで削除は不要だったので、そのまま進めた。 自分で仕掛けた安全装置が、共有リポジトリを触る場面で働いた。
レビュー版を並べて比べる
別プロジェクトで作った計画書のレビュー資料も、同じ共有リポジトリへ出した。 既存の計画書をCodexにレビューさせた版と、そのレビューにさらに自前のスキルを重ねた版がある。 3つのカラムで並べて読めるHTMLと、指摘ごとに承認かそのままかコメントかを判定させるビューアも作ってあった。 画像を含めて38ファイル、4.7MBあった。
ローカルにクローンがあるはずだと思って探したら、その名前のディレクトリは存在しなかった。 リモートには同じ用途のリポジトリがあったので、新しくクローンして中へ入れ、pushした。
一日の終わりに、積み残しを並べ直す
夜になって、もう一度積み残しを一覧にしてもらった。 日中と同じ作業だが、一日でリストの中身は入れ替わっている。
先頭に来たのは、その日の夕方に自分で足した項目だった。 一覧の全件出力を任意のタイミングで取ってきて、前回のCSVとの差分をHTMLで報告する。 出力は年単位でしか取れない作りなので、差分は自分で取るしかない。 ブラウザを叩きながら通信を読んで仕様をスキルに落とす、というこの日と同じ手順を、もう一度別の画面でやることになる。
ほかに、読み取り調査の未了分、議事録の保存先についての返答待ち、計画書プロジェクトの次フェーズ、前日に出たデータの要確認8件が残った。
そこからもう一段、計画書プロジェクトの筋道を整理した。 今は既存の計画書をAIにレビューさせ、こちらからフィードバックする形で進めている。 一方で、市販の書籍をもとに簡易な事業デューデリジェンスと財務デューデリジェンスを回すスキルを、別のリポジトリで作りかけている。 そちらが動けば、レビューを待たずに計画書の初期仮説を先に立てられる。 手元の蔵書に使える本があるかを確かめるため、書籍DBを横断で検索した。 取り込み済みが362冊、棚全体では1,333件あった。
今日の学び
- 内部ドキュメントが2本あって食い違ったら、画面に出ているラベルが一番強い証拠になる。ドキュメントの新しさや詳しさでは決まらない
- 読み取り調査で分かるのは「何を送るか」までで、「どう送るか」は1件登録してみないと出てこない
- テキストで書いた仕様は、追記のたびに壊れても誰も教えてくれない。スキーマと検証スクリプトを置くと、壊れたときに気づける
- 選択肢マスタは先に全部取ってJSONへ入れる。1回の手間で、以後は実機に触らずに済む
- 同じ質問に見える確認を2度させたら、説明がつくかどうかとは別に、聞き方の設計が悪い