はじめに

こんにちは、LayerX バクラク事業部で請求書発行を担当している QAエンジニアの genny です！

最近、API の自動テストを実装する中で、プロダクトコードの処理フローを追う必要に迫られました。Cursor を活用することでスムーズに理解を深めることができたので、その過程で得た知見を共有できればと思います。

なぜプロダクションコードを読む必要があったのか

以前のチームでは Ruby on Rails のシステムに携わっており、その時はある程度コードを読めるようになっていましたが、バクラクのバックエンドで採用されている GraphQL や Go で実装されたシステムに携わった経験がありませんでした。さらに、入社後半年が経過しても、業務の優先度の関係で十分なコードリーディングの時間を確保できていませんでした。

そんな中、自動テストを実装する際、複数のステップを経て API リクエストを行い、レスポンスを元にアサーションを行うような自動テストを書く機会がありました。しかし、コードレビューで「この CreateDocument API の処理には非同期で実行される部分がありませんか？アサーションを実行する前に処理が完了していることを保証するために、適切な待機処理を入れるべきではないですか？」（実際はもっと優しい口調です）という質問を受けました。

この質問を受け、実装したテストの妥当性を担保するために、書類を作成する処理である CreateDocument API の処理を詳細に追う必要が生じました。その際に、Cursor の Agentモードを活用して該当の処理の流れを確認することができたため、その概要を紹介します。

前提

前提となるアーキテクチャやテックスタックなどは、下記の通りです。バクラク事業部プロダクト開発部部長の @sh_komine さんの発表スライドにまとまっています。

今回対象にしたのは Backend の Go で書かれたシステムで、 graphql-gateway で定義されている Query や Mutation が呼ばれた後の処理がどうなっているか理解したく調査を行いました。

Cursor Agent モードとの出会いと活用

前述の通り、私は Go と GraphQL はほぼ未経験でした。なので、スキーマファイルを見て該当の Query や Mutation を見つけてもその先の処理の追い方が分かりませんでした。そこで Cursor を使ってコードを追って理解を進めていくことはできないかと考えました（以前からソフトウェアエンジニアの方に何度か相談してはいて、「もしかしたらいけるかもね〜」くらいの話はしていました）。

Cursor 初心者だった私は、まず Ask モードを使用し、「CreateDocument の実装はどのファイルを見ればよいか？」と質問しました。すると、「Agent モードで『CreateDocument の実装ファイルを探して』と依頼すると良い」というアドバイスが返ってきました。

そこで Agent モードに切り替えて検索を依頼すると、具体的なファイル名と実装箇所を特定することができました。Agent モードは、検索プロセスを逐一表示し、どのようにファイルを特定したのかを明示してくれる点も非常に役立ちました。

下記はその一部です（実際にはもっと色々やり取りがあります）。

Search files...
タイムアウトが発生したため、別のアプローチで検索してみます。GraphQLのリゾルバーは通常特定のディレクトリパターンに従っているので、まずディレクトリ構造を確認します。

Ran tool
ソースコードはsrcディレクトリにあるようです。次に、srcディレクトリの構造を確認します。

Ran tool
GraphQLのリゾルバーは通常schemaディレクトリにあることが多いので、そこを確認します。

Ran tool
documentディレクトリがあるので、これがCreateDocumentの実装がある可能性が高いディレクトリです。このディレクトリの内容を確認します。

Ran tool
document.tsファイルが最も可能性が高いファイルです。このファイルは2000行以上あり、おそらくCreateDocumentの実装が含まれていると思われます。このファイルの内容を確認します。

Ran tool
476行目にCreateDocumentのミューテーションフィールドの定義が見つかりました。このファイルの該当部分を詳しく見てみましょう。

Read file: `fileへのpath` の実装を見つけることができました。実装は以下のファイルにあります：

`relative path` 含むファイル名の476-490行目

実装の詳細は以下の通りです：

// 実際のコードがここに出力されている

この実装では、GraphQLリゾルバーがメソッド名メソッドを呼び出して実際のドキュメント作成処理を行っています。引数としてdeepExcludeNull(args)を渡しており、これはnull値を除外する処理を行っています。

実際のビジネスロジックはサービスのcreateメソッドに実装されていると思われます。

上記のようにどのメソッドにロジックが実装されているかまで特定できました。

Cursor Agent との対話

コードを理解するために、私は Cursor に以下のような質問をしました：

「CreateDocument メソッドの実装はどこにありますか？」
「document_item テーブルの構造について教えてください」
「document_action_log テーブルの構造について教えてください」
「CreateDocument メソッドの処理フローを教えてください」
「テーブルへのデータ書き込み処理はどこで行われていますか？」
「この処理は同期的に実行されますか、それとも非同期処理がありますか？」

これらの質問を通じて、CreateDocument APIの処理の全体像を理解することができました。

CreateDocument APIの処理の理解

Cursor の回答を整理して、 CreateDocument API のレスポンスが返ってきた時点で、ドキュメント関連の必要なデータベースレコードは全て作成完了しており、CreateDocument API のレスポンスを取得した直後にアサーションをしてしまっても問題ないことがわかりました。

この調査により、実装すべきテストの要件が明確になり、適切なアサーション方法を選択することができました。

念の為、調査結果を同じチームのソフトウェアエンジニアにも確認してもらい認識に間違いがないことをダブルチェックしてもらいました。

感想

開発経験のない QAエンジニアにとって、未経験のテックスタックを理解するのはそれなりにハードルが高いと思います。Cursor はハードル低く気軽に聞ける相手という感じで、プロダクトの理解にとても役立つと感じています。（ちなみに、弊社のソフトウェアエンジニアはとても協力的なので、「ここのコードを詳しく知りたいのですが…」とお願いすれば、快く教えてくれます。）

最近は、Cursor の Agent モードを使って下記のようなことも行えるようになってきており、ツールを経由してできることが増えました。

バグの修正
- エラーが起きている画面や処理を特定してエラーメッセージを渡すと、簡単なものであれば修正箇所を示してくれます(まだ 1 つですがバグの修正 PR を出してマージすることができました)
エラーの調査
- 問い合わせやテスト中に起きたエラーのアクセスログを Cursor に渡すことで、エラーの原因や怪しい箇所を教えてくれて、調査のとっかかりにとても役立っています