テーマを選び、作り上げ、きちんと書く

このコースの第 1 部で、私たちは一緒に RepoBot を作りました。httpx の質問に答えるアシスタントで、v1 のコマンドラインのチャットプログラムから、v4 の Web サービスまで作り、検索も、エージェントも、評価も、ガードレールも備えています。

修了プロジェクトでは、この道をもう一度一人で歩いてもらいます。ただし今回はテーマをあなた自身が決めます。この課では新しい技術は教えません。扱うのは、プロジェクトを本当にやり遂げる方法です。

テーマを選ぶ

よい修了プロジェクトのテーマは、次の条件を満たします。

• あなた自身か身近な人が本当に使う。本物のユーザーがいてこそ、使いやすいかどうかがわかり、やり遂げる動機も生まれます。
• はっきりした正誤がある。答えが正しいか、分類が正確か、抽出したフィールドがそろっているかを、チェックできること。「よい詩を書く」のようなテーマは評価しにくく、修了プロジェクトには向きません。
• 2～4 週間で最初の使える版を作れる。小さくてもいいので、やり遂げることです。
• データが手に入り、使う権利もある。公開されたドキュメント、自分のノート、オープンソースのデータセットならどれでもかまいません。社内のデータなら、使ってよいか、API に送ってよいかを先に確かめてください。

参考になる方向をいくつか挙げます。どれもコースのいくつかのモジュールに対応しています。

题目                                    主要用到
给你常用的一个开源库做答疑助手          RAG（04）、评估（06）
读懂一个代码仓库、回答"这个函数在哪里   智能体和工具（05）、MCP（05 第 7 课）
被调用"的助手
从简历、合同、发票里抽取固定字段        提示词和 JSON 输出（02）、评估（06）
把客服工单自动分类，并给出建议回复      提示词（02）、模型评委（06），可能用到微调（10）
在某个领域的文字上训练一个小模型        第 09 模块，外加第 08 模块第 6 课的过拟合检查
（比如宋词、对联、自己的聊天记录）

「汎用の AI アシスタントを作る」のようなテーマは選ばないでください。境界がなく、いつまでも終わらず、評価もできません。

第一歩：完成の基準を書き留める

手を動かす前に、GOAL.md を一つ書き、三つの問いだけに答えます。

1. 誰が使い、何の問題を解決するのか。一文で。
2. 完成とはどういう状態か。このコースの各モジュールの冒頭にある「修了の目安」のように、チェックできるいくつかのことに書きます。たとえば「httpx のドキュメントの使い方の質問に答えられ、20 問の評価問題で 16 問以上正解し、どの回答にも出典がある」「1 問あたりの平均費用が 0.01 元を超えない」。
3. 何をしないかをはっきりさせる。たとえば「画像のアップロードには対応しない」「中国語だけに対応する」。

このファイルが、あなたのプロジェクトがいつ完成とみなされるかを決めます。これがないと、プロジェクトはどんどん大きくなりがちで、最後には何もやり遂げられません。モジュール 07 第 3 課でも同じことを言いました。先に受け入れ基準を決め、それから手を動かす。

第二歩：先に評価セットを作る

機能のコードを一行も書く前に、20～50 問の評価問題を用意します。

本末転倒に聞こえますが、これがプロジェクト全体で最も重要なステップです（モジュール 06 第 1 課）。

• 問題を書く過程で、ユーザーが実際に何を聞くのか、どんな回答がよいのかを考え抜かざるをえなくなります。
• 評価セットがあれば、変更するたびに、効果がよくなったのか悪くなったのかをコマンド一つで知ることができます。
• 最後に README を書くとき、「効果はとてもよい」ではなく、本当の数字を書けます。

問題は普通の質問をカバーするだけでなく、境界ケース、回答を断るべき質問、悪用されうる入力も含めるべきです（モジュール 06 第 5 課）。

第三歩：最も単純な使える版を作る

まず最も単純な方法で一つの版を作り、評価セットを一通り実行します。

RepoBot の v1 がわざと何の資料も調べなかったのは、「最も単純な方法」でどこまでできるのか、そしてどこで失敗するのかをはっきり見るためでした。その失敗が、次に何を最もすべきかを教えてくれます。資料を知らないせいで間違えているなら RAG を加える。何ステップも調べる必要があるせいで間違えているならエージェントを検討する。形式が安定しないだけなら、まずプロンプトを直す。

学んだ技術を最初からすべて使わないでください。モジュール 05 第 1 課で言ったとおり、単純なワークフローで解決できる問題に、エージェントを使うべきではありません。何か一つ加えるたびに、それが本当に効果をよくしたことを示す評価結果が必要です。

第四歩：小さなステップで改善する

その後の各ステップは次のとおりです。

1. 評価結果の中で失敗した問題を見て、最も主な種類の失敗を見つける。
2. その種類の失敗を狙って、変更を一つ加える。
3. もう一度評価セットを実行し、結果を記録する。
4. git でコミットし、コミットメッセージに評価結果の変化を書く。

各ステップの評価結果を一つの表に記録しておきましょう。README を書くとき、この表が最も説得力のある内容になります。どの設計の決定にも理由があったことを示してくれるからです。

版本    改动                          答对      平均花费/题   平均耗时
v1      直接问模型                    7/20      0.002 元      2.1 秒
v2      加上 RAG（向量检索）          13/20     0.004 元      3.0 秒
v3      改成混合检索 + 重排           16/20     0.004 元      3.4 秒

（上の表は形式の例で、本物のデータではありません。あなたの表には、自分で実行して得た数字を入れてください。）

第五歩：公開前のチェック

プロジェクトを他の人に使ってもらうなら、モジュール 06 と照らし合わせて一通りチェックします。

• キーがコードに書かれておらず、git にもコミットされていない。
• 入力の長さの制限と呼び出し頻度の制限があり、誰かにお金を燃やされることがない。
• ログで各リクエストのステップ、所要時間、費用が見えるが、ユーザーの機密情報は記録していない。
• 入力と出力のガードレールがあり、評価セットで正常な質問を巻き添えにしていないことを確かめてある。
• エージェントを使っているなら、それが呼び出せるツールの権限は最小限になっている（モジュール 05 第 8 課）。

第六歩：README を書く

どれほどよくできたプロジェクトでも、他の人が読んでわからず、動かせなければ、作っていないのと同じです。README には少なくとも次のものが必要です。

• 一文の説明：それが何で、誰のためのものか。
• 効果：本当の使用例を一つか二つ（実際に実行した出力で、でっち上げないこと）と、評価結果の表。
• 動かし方：コードのクローンから結果を見るまでの完全な手順で、他の人がそのとおりに一度やれば動かせるもの。どんな環境変数が必要か、おおよそいくらかかるかをはっきり書きます。
• どう設計したか：全体の構成と、要となるいくつかの決定とその理由（なぜファインチューニングではなく RAG を使ったのか、なぜこのモデルを選んだのか）。
• うまくできないところ：評価セットでまだ間違えている問題がどんな種類か、わかっている制限。

最後の項目は最も省かれがちですが、あなたの力量を最もよく示す部分です。自分のシステムがどこで間違えるのかをはっきり言えることは、あなたがそれを本当に理解している証拠です。モジュール 06 の RepoBot v4 も、README に「公開前にまだ何が足りないか」を並べていました。

書き終えたら、このプロジェクトを見たことのない友人を一人見つけ、README だけを見てプロジェクトを動かしてもらってください。その人がつまずいたところは、どれも README を直すべきところです。

人に説明する

最後に、自分のプロジェクトを 5 分で人に説明してみてください。Start AI Engineering のコースがまとめた一組の問いを借りて組み立てられます（モジュール 03～06 のプロジェクトの課の最後でも使いました）。

1. それはどんな問題を解決していますか？誰が使っていますか？
2. 入力は何で、出力は何ですか？
3. なぜこの方式を選び、もっと単純な、あるいはもっと複雑な方式にしなかったのですか？
4. それがよいかどうかを、どうやって知るのですか？数字はいくつですか？
5. 1 回の呼び出しにいくら、どれくらいの時間がかかりますか？
6. それはどこで間違えますか？間違えたらどうなりますか？

この六つの問いにはっきり答えられれば、あなたはもう「LLM を呼び出せる」だけではなく、信頼できる AI アプリを一人で作れるようになっています。それこそが、このコースが最初の課からあなたを連れて行きたかった場所です。

練習問題

1. 候補のテーマを三つ書き出し、この課の「テーマを選ぶ」の四つの条件でそれぞれ採点して、一つを選んでください。
2. 選んだテーマについて、GOAL.md と少なくとも 20 問の評価問題を書き、それからコードを書き始めてください。
3. やり遂げたら、README をこのプロジェクトを見たことのない人に渡し、その人がどこでつまずいたかを記録して、README を直してください。

確認テスト

1. 機能のコードを書く前に、先に評価セットを用意するのはなぜですか？

評価問題を書くことで、ユーザーが何を聞くのか、どんな回答がよいのかを考え抜かざるをえなくなります。評価セットがあれば、変更のたびに効果がよくなったかをコマンド一つで判断できます。最後に README を書くときにも本当の数字があります。評価セットがなければ、いくつかの例の感覚で判断するしかなく、判断を誤りやすくなります。

2. 最初から RAG やエージェントといった技術を使うのではなく、まず最も単純な版を作ることを勧めるのはなぜですか？

最も単純な版は、問題が実際にどこにあるのかを教えてくれます。資料が足りないのか、何ステップもの操作が必要なのか、形式が安定しないだけなのか。失敗の原因に応じて技術を選び、何か一つ加えるたびに評価結果でそれが役に立つことを示せば、システムを必要以上に複雑にするのを避けられます。

3. README に「うまくできないところ」を書くのはなぜですか？

どんな場合にこのシステムを頼ってはいけないかを使う人に伝え、誤用を防げるからです。作者が自分のシステムを本当に理解し、どこで間違えるのかを知っていることも示せます。長所だけを書いた README は、かえって信頼しにくいものです。