cert-question-bank
資格試験(AWS 認定など)の問題集とアーキテクチャ説明ガイドを、ビルド不要の静的サイトとして作成・拡充・検査するための手順とノウハウ。 このリポジトリ(AIP-C01 の問題集)で問題を追加・修正するとき、別の試験の問題集を同じ方式で作るとき、 「問題を作って」「問題集を増やして」「選択肢の長さで正解がばれる」「Well-Architected に沿って正解を決めて」 「ガイドにサービスを追加し
SKILL.md.claude/skills/cert-question-bank/SKILL.md
GitHub資格試験の問題集・ガイドの作り方
AIP-C01(AWS Certified Generative AI Developer – Professional)の問題集 450 問とガイドを作ったときのノウハウです。 問題の追加・修正にも、別の試験の問題集を新しく作るときにも使えます。
1. 全体の進め方
- 出題範囲を確定する。 試験ガイドの分野・配点・タスク、対象サービス(In-Scope Services)を集め、
data/meta.jsのDOMAINSに配点と 1 回あたりの問題数(perSet)を書く。- 1 回あたりの問題数は「配点 × 問題数」を丸めて、合計がちょうど回の問題数になるように調整する(AIP-C01 は 75 問で 23-20-15-9-8)。
- 正解の判断基準を決める。 「どのベストプラクティスに沿っているか」で正解を決める(AIP-C01 は Well-Architected Generative AI Lens)。基準のベストプラクティス一覧を
WAに ID → [柱, 日本語の名前] で登録し、各回ですべてを扱う。- 内容を確認できないベストプラクティスは推測で入れずに除外し、そのことをユーザーに伝える(
GENREL04-BP01はこの理由で除外)。
- 内容を確認できないベストプラクティスは推測で入れずに除外し、そのことをユーザーに伝える(
- 根拠のドキュメントを登録する。
DOCSにキー → [タイトル, URL] で登録し、問題のrefからキーで参照する。 - まずサンプル 10 問 → フィードバック → 量産 の順で進める。最初から大量に作らない。
- 1 回分ずつ作り、1 回ごとにコミットする(
Add exam set N (75 questions))。1 回分は分野ごとに 4 ファイルに分ける(a: 第1分野、b: 第2分野、c: 第3分野、d: 第4・5分野)。ファイルが大きすぎると書き込み・修正が難しくなるため。 - 作成途中は
node tools/check-questions.js --partial、1 回分が揃ったら--partialなしで検査する。 - ブラウザで全問を通して解き、JS のエラーがないことを確かめる(→ 6 章)。
- README、ガイド、
quiz.htmlの<script>タグを更新し、コミット・プッシュする。PR はユーザーに頼まれたときだけ作る。
2. 問題の書き方
問題のデータの形とサンプルは references/question-format.md を見ること。
- 実際のユースケースを前提にする。 業界・会社・業務の状況と、制約(コスト、レイテンシ、規制、運用の手間、既存の構成など)を問題文に入れ、「最も適切な設計・対応」を選ばせる。
- アーキテクチャの構成を問う(ユーザーの指摘)。ビジネスの判断を問う問題にしない。
- 問題文:ユースケースは残し、要件・制約を技術的に書く(件数、レイテンシ、RPO、閉域、運用の人数など)。「最も適切な構成はどれですか。」で問う。
- 選択肢:4 つともサービス・設定・データの流れなどの具体的な構成案にする。
- 選択肢にしないもの:何もしない、機能をやめる、人の手作業、社員への周知、契約や規程、提供元を待つ。
- 人の確認は、構成の要素として書く(Step Functions のタスクトークン、Amazon A2I など)。
- 確認には
node tools/lint-architecture.js <回>を使う(業務の判断に見える選択肢を一覧にする。目安)。
- 複数のサービスを組み合わせる。 1 つのサービスの機能を問うだけの知識問題にしない。
- 正解はベストプラクティスに沿っているかで決める。 解説(
exp)の書き出しを「GENxxx-BPyy は、〜を推奨しています。」にして、なぜ沿っているかを書く。 - 誤答も「ありそう」にする。
- 「何もしない」「全部手作業」のような明らかな誤りだけにしない。
- 一見よさそうだが、過剰な権限、単一障害点、コストの無駄、運用の手間、制約を満たさない、などの理由でベストプラクティスに反するものにする。
whyに選択肢ごとの正誤の理由を書く(正解は「正解。」で始める)。- 不正解の理由は、なぜ誤りかが学べるように書く(ユーザーの指摘)。一言で済ませず、30〜120 文字・2 文程度にする。
- 1 文目:問題文のどの要件・制約(コスト、運用負荷、規制、権限など)に照らして、何が問題か。
- 2 文目:どの原則に反するか、代わりに何をすべきか。
- 一部は正しい選択肢には「〜はできるが、〜は防げない。」と書く。
- 先頭に「誤り。」は付けない。画面で「不正解」と表示する。
- 画面では、解説の中に「選択肢ごとの解説」として、表示の順番で全選択肢の正誤と理由を並べる。
- 重複は不可。 サービスの重複はよいが、同じ状況・同じ論点の問題は作らない。業界と論点をずらす。検査スクリプトが問題文の類似度(文字 3-gram の Jaccard 係数 0.45 以上)で検出する。
- 知識分野を示す。
t(試験のタスク)とtopic(何の知識か)を必ず付ける。画面に表示される。 - 複数選択の問題 は「2 つ選んでください」とし、選択肢を 5 つにする。1 回に 3〜4 問程度。
3. 選択肢の長さで正解がばれないようにする
ユーザーから最初に指摘された点。検査スクリプトのルール:
- 正解が他のどの選択肢よりも長い問題は不可(同じ長さは可)。
- 正解が一番短い問題は 1 回の 35% 以下(実績は 16〜25 問 / 75 問)。
作るときのコツ:
- 正解は条件を書き込みすぎて長くなりがち。誤答にも同じくらい具体的な条件・理由を書く(「〜のため、〜する」「〜して、〜にする」)。
- 英字のサービス名(
Amazon Bedrock Knowledge Basesなど)は文字数を大きく増やす。正解だけにサービス名を入れない。誤答にもサービス名を入れるか、正解では一般名詞で書く。 - 短すぎる誤答(「何もしない」など)は、正解を一番長くする原因になり、誤答としても明らかすぎる。完全な文に書き直す。
- 調整は
node tools/show-choices.js 3-12 3-15で文字数を見ながら行う。正解が一番短い問題のうち差が小さいものはnode tools/near-shortest.js <回>で探す。 - 大量の書き換えは、
[[置換前, 置換後], ...]の JSON を作ってpython3 tools/replace.py <ファイル> <表.json>で一括で行う。置換前が見つからなければエラーで止まる。
正解の位置の偏り も確認する。作ると正解が 2 番目に偏りやすい(実績では 430 問中 299 問)。そのため、addQuestions は問題 ID をシードにして選択肢の並びを決めている(seededOrder、FNV ハッシュ)。データは正解をどこに書いてもよい。シャッフルを切っても偏らない。
4. サイトの作り
ビルド不要の静的サイト。 HTML + CSS + 素の JS。GitHub Pages で公開し、
.nojekyllを置く。セキュリティ:
- すべての HTML に CSP の meta を入れる:
default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data:; object-src 'none'; base-uri 'none'; form-action 'none'。 - インラインスクリプトと外部 CDN は使わない。
- 問題データを DOM に入れるときは
textContentを使う。HTML を組み立てるときは、必ずesc()(& < > " 'をエスケープ)を通す。 target="_blank"のリンクにはrel="noopener"を付ける。- localStorage の読み書きは try/catch で囲み、壊れた値でも動くようにする。
- すべての HTML に CSP の meta を入れる:
データの読み込み:
data/meta.js→data/set1-a.js〜set6-d.jsの順にquiz.htmlで<script>タグを並べる。回を増やしたらタグも増やす。UI は「AI っぽく」しない(ユーザーの指摘):
- グラデーション、角丸の大きいカード、影、絵文字、ピル型のバッジは使わない。
- 参考書のような落ち着いた見た目にする:白に近い紙の色、罫線、見出しの下線、アクセント色は 1 色(紺)、和文のゴシック体で行間を広く(
line-height: 1.85)。 - 色はすべて
:rootのトークンで定義し、ダークモードをprefers-color-schemeと[data-theme]の両方で切り替える。 [hidden]{display:none!important}を入れておく(displayを指定した要素にhiddenが効かない問題の対策)。
トップページは情報を絞る。 問題数の一覧などのカラムは置かない(ユーザーの指摘)。
問題集の画面:
- 回の選択、分野の絞り込みを置く。分野ごとの問題数は選んだ回の数を出す。
- 解答後に、正誤、選択肢ごとの理由、判断基準のベストプラクティス(柱・ID・名前・リンク)、根拠のドキュメントを表示する。
- 結果は分野別と柱別に出す。
- 10 問ずつの演習モード:
- 選び方は、問題番号の順に区切った範囲と「おまかせ」(未解答 → 前回不正解 → 前回正解の順に優先)。
- 結果の画面に「次の 10 問へ」と「同じ問題をもう一度」を置く。
- 出題方式は localStorage に保存する。設定の画面に戻っても、選んでいた回を保つ。
ガイド: サービスを生成 AI アプリの層(モデル、データ/RAG、エージェント、統合、安全性、運用、セキュリティなど)で整理する。頻出パターン、判断表、サービスごとの「役割・使いどころ・試験の着眼点」、ベストプラクティスの一覧を載せる。
公開とライセンス:
- 公開リポジトリには OSS のライセンス(このリポジトリは Apache 2.0)、著作権表示の
NOTICE、README の「ライセンス」と「免責事項」を置く。 - 免責事項には、AWS の公式の教材ではないこと、サービス名は商標であること、実際の試験問題ではないことを書く。
- Apache 2.0 では、問題や解説の文章も商用を含めて再利用できる。商用利用を制限したい場合は、文章だけ CC BY-NC などにする選択肢がある。ただし、その部分は OSS ではなくなる。
- 公開リポジトリには OSS のライセンス(このリポジトリは Apache 2.0)、著作権表示の
5. 作業環境の注意(クラウドのセッション)
- docs.aws.amazon.com と WebFetch は、ネットワークの設定でブロックされることがある。 WebSearch で事実と URL を集める。確認できなかった URL は推測で書いたことを、ユーザーへの報告と PR に必ず明記する。
git pushが 403 になったら、 GitHub の接続や権限が足りない。ユーザーに GitHub の再接続・権限付与を頼む(read_documentationのgithub.accessを参照)。ghCLI は使えない。PR は GitHub の MCP ツール(mcp__github__create_pull_request)で作る。node -eの中ではシェルの変数を使えない。exportしてからprocess.envで読む。
6. 確認の手順
node tools/check-questions.jsがOK: <問題数> 問で終わること。次を確かめる:- 各回の問題数と分野の配分
- 未使用のベストプラクティスが 0
- 正解の長さのルール
- 類似した問題がないこと
- Playwright(Chromium は導入済み。
playwright installはしない)でquiz.htmlを開き、次を確かめる:- 回ごとに全問を解いて、
pageerrorとconsole.errorが出ないこと - 毎回 1 つ目の選択肢を選んだときの正答率が 25% 前後になること(正解の位置が偏っていないこと)
- 分野の絞り込みと回の切り替えで、問題数の表示が変わること
- 幅 390px で横にはみ出さないこと
- ライト/ダークの両方のスクリーンショットを撮って見た目を確かめること
- 回ごとに全問を解いて、
- Playwright で同じボタンを続けて押すと「element detached」になる。
page.locator(sel).nth(i).click()を使う。
7. ユーザーへの報告
- 日本語で、何を作ったか(問題数、構成、基準)、どう確かめたか、注意点(確認できなかった URL、除外したベストプラクティス)を短く書く。
- PR は頼まれたら作る。本文は「概要/変更内容/確認したこと/注意点」の構成にする。