メガベンチャーという急成長の渦中において、開発チームの独立性はスピードの源泉です。 しかし、組織が拡大し、プロダクトやマイクロサービスが複雑に絡み合うフェーズに差し掛かると、これまでの「チームごとの個別最適」は限界を迎えます。 「隣のチームと品質基準が異なり、連携部分で障害が多発する」 「リリース直前の手戻りが増え、QAがボトルネック視されている」 「属人化したテスト運用により、組織のスケールに品質体制が追いつかない」 QAマネージャーや品質推進リードが直面するこれらの課題は、単なるリソース不足ではなく、組織全体の「テスト管理戦略」の欠如に起因しています。 QAはもはや、不具合を見つけるだけの「最後の砦」ではありません。 スピードと品質を両立させ、ビジネス価値を最大化する「事業成長の設計者」へと脱皮する必要があります。 そこで今回は大規模プロジェクトに適したテスト管理の全体設計から、現場と経営を繋ぐ可視化の仕組み、そして組織をパートナー型QAへと変革するロードマップまで、論理的かつ実践的なアプローチを詳しく解説します。 import haihaiInquiryFormClient from "https://form-gw.hm-f.jp/js/haihai.inquiry_form.client.js";haihaiInquiryFormClient.create({baseURL: "https://form-gw.hm-f.jp",formUUID: "927d2c4e-f06c-45b1-bd36-0240e55ccf72",}) ▼テスト計画・テスト設計についてはこちら▼ テスト設計とは？その流れや具体的なコツを徹底解説！ なぜ今、メガベンチャーに「全体最適のテスト管理」が必要なのか チームごとにバラバラな基準が生む手戻りと障害増加 急成長を遂げるメガベンチャーにおいて、プロダクトごとに開発チームが独立して動く体制はスピード面で大きな利点があります。 しかし、それぞれのチームが独自の判断でテスト方針や品質基準を運用し始めると、組織全体で見れば深刻な摩擦が生じます。 結果として、リリース直前に他チームとのインターフェース不整合が発覚し、大規模な修正やスケジュール延期を余儀なくされるケースは少なくありません。 共通の物差しがない状態では、障害が発生した際の原因究明も難航し、現場の疲弊を招くだけでなく、ユーザーからの信頼を損なうリスクも高まります。 大規模プロジェクトにおいては、個別のスピード感を尊重しつつも、組織として譲れない一貫した品質の防衛線を引くことが、最終的な手戻りを最小化する鍵となります。 部分最適を積み上げても、組織全体の品質は上がらない理由 各チームがそれぞれの担当範囲で品質を追求する「部分最適」は、一見すると正しい努力に見えます。 しかし、複雑に絡み合う複数のプロダクトや基盤システムを持つ組織では、個別の最適化が必ずしも全体の成果に直結するわけではありません。 例えば、特定の機能でテストカバレッジを100％に近づけたとしても、それをつなぎ合わせるシステム全体のシナリオテストが疎かであれば、サービスとしての価値は担保できません。 また、各所で作られる独自のテストドキュメントや管理ツールは、知見の共有を阻害し、車輪の再発明を繰り返す原因となります。 QAマネージャーが注力すべきは、各ポイントの精度を上げること以上に、プロダクト間の境界線やデータフローを俯瞰した管理構造の構築です。 全体を貫くテスト戦略が不在のままでは、どれほど個々のテストを自動化しリソースを投入しても、組織としての品質レベルは頭打ちになり、非効率なコスト増大を招くだけの結果に終わってしまいます。 QAが「最後の砦」ではなく「事業成長の設計者」になるための視点転換 従来のQAは、開発プロセスの終盤で不具合を検出する「ゲートキーパー」や「最後の砦」としての役割を強く期待されてきました。 しかし、変化の激しいビジネス環境において、その役割に固執することは、皮肉にもリリースを阻むボトルネックとして扱われるリスクを孕んでいます。 今求められているのは、品質を単なる欠陥の有無ではなく、事業の競争力を支える戦略的資産と捉える視点の転換です。 QAリードは、開発初期段階からプロダクトマネージャーや経営層と並び、どのレベルの品質がビジネス上の優位性をもたらすのかを定義する立場に回る必要があります。 テストを「守り」の作業から、自信を持ってプロダクトを市場に送り出すための「攻め」の設計プロセスへと昇華させることで、QAは組織における価値創出の中核へと変化します。 品質を制御可能な変数として捉え、事業戦略と連動したテスト管理を行うことが、持続可能な成長を支える土台となるのです。 急成長フェーズで破綻しやすい品質体制の共通パターン 組織が拡大し、エンジニアの数やプロダクト数が急増するフェーズでは、かつて機能していた暗黙知ベースの運用が通用しなくなります。 この時期に多くの企業が陥る失敗パターンは、場当たり的な人員補充による属人化の加速です。 標準化された管理プロセスがないまま人だけを増やしても、担当者のスキルや経験によってテストの精度が大きく揺らぎ、結果として管理コストだけが増大する悪循環に陥ります。 また過去の成功体験に縛られ、小規模チーム時代の密なコミュニケーションに依存した品質管理を続けてしまうことも、組織崩壊の予兆です。 ドキュメント化の遅れや品質メトリクスの不在により、全体像が見えなくなった状態で大規模なシステム変更を行うと、どこに影響が出るか誰も把握できないブラックボックス化が進みます。 こうした破綻を防ぐためには、成長の痛みが生じる前に、属人性を排除した構造的なテスト管理体制へと移行し、スケーラビリティを担保した組織設計を先手で進めておくことが不可欠です。 全体を俯瞰して設計する ― 大規模プロジェクトのテスト戦略 企画・設計段階から品質を組み込む考え方 大規模プロジェクトにおいて、テストを開発の最終工程として捉える従来の手法は、手戻りによるコスト増大を招く大きな要因となります。 品質を後から付け加えるのではなく、企画や要件定義の段階から品質の概念を組み込む「シフトレフト」の考え方が不可欠です。 プロダクトマネージャーや開発者と早い段階で対話を持ち、仕様の矛盾やテストのしにくさを初期に解消しておくことで、後の工程での大幅な修正を防ぐことができます。 これは単にバグを早く見つけるという話にとどまらず、事業が目指す価値が技術的に正しく実現可能かどうかを検証するプロセスでもあります。 QAマネージャーとしては、要件定義書を確認するだけでなく、ビジネス要件からどのようなテストシナリオが必要になるかを早期に提示し、チーム全体で品質に対する共通認識を形成することが求められます。 上流工程での働きかけが、結果として開発サイクル全体のスピードを高め、リリース直前の不確実性を排除する土台となります。 共通の品質基準を定義し、組織横断で揃える方法 マイクロサービス化が進み、複数のチームが独立して動くメガベンチャーでは、チームごとに品質へのこだわりが異なり、全体の整合性が崩れがちです。 これを解消するためには、組織全体で遵守すべき「共通の品質基準」を明文化し、標準化する必要があります。 まずはどのプロダクトにおいても最低限クリアすべき品質のボーダーラインを「品質特性」などのフレームワークを用いて定義します。 ただし、一律の基準を押し付けるだけでは現場の反発を招くため、各プロダクトのフェーズや特性に合わせてカスタマイズできる柔軟性も持たせることが重要です。 定義した基準は、チェックリストやテスト管理ツールを通じて各チームが日常的に参照できる状態にします。 これにより、QA担当者の主観に頼らない客観的な評価が可能となり、組織全体の品質が一定のレベルを下回らない仕組みが構築されます。 共通言語を持つことで、チームを跨いだ不具合報告や改善提案もスムーズになり、組織としての品質推進力が大幅に向上します。 リスクと事業インパクトを軸にした優先順位の決め方 すべての機能を網羅的に、かつ最高レベルの精度でテストすることは、限られたリソースとスピードが求められる環境では現実的ではありません。 そこで重要となるのが、リスクベースドテスティングの視点を取り入れた優先順位付けです。 具体的には、その機能に不具合が生じた際の「事業への影響度」と、技術的な「不具合の発生確率」の二軸でテストの比重を判断します。 決済システムや個人情報に関わる基幹部分など、障害が即座に大きな損失につながる領域にはリソースを厚く配分し、UIの微細な調整など影響が限定的な部分は自動化や簡易的な確認に留めるといった強弱をつけます。 この判断基準をPdMや経営層と共有しておくことで、万が一の障害発生時やリリース判断の際にも、論理的な裏付けを持って対話ができるようになります。 リスクを可視化し、戦略的に「何を捨て、何を守るか」を意思決定することが、大規模プロジェクトを管理するリードの重要な責務です。 「どこまでやるか」を明確にするテストの線引き テスト活動において最も難しい課題の一つが、終了条件の定義、つまり「どこまでやれば十分か」という線引きです。 終わりなきテストはリリースのボトルネックとなり、逆に不十分なテストは信頼を失墜させます。 この線引きを明確にするためには、事前に定義した品質基準に基づき、テスト完了条件（Exit Criteria）を定量的に設定しておくことが不可欠です。 例えば重要なテスト項目の消化率だけでなく、未解決バグの数や重要度、自動テストの成功率、特定のコードカバレッジといった指標を組み合わせます。 また、全ての不具合をゼロにすることを目指すのではなく、許容可能なリスクの範囲を合意しておくことも重要です。 この線引きが明確であれば、現場のメンバーは迷いなく作業に集中でき、マネジメント層も自信を持ってリリースの決断を下せます。 属人的な判断を排し、あらかじめ合意されたルールに基づいてテストを終了させる仕組みを整えることが、持続可能な品質管理体制を実現するための最後の一歩となります。 マイクロサービス・複数プロダクトを横断する仕組みづくり サービス単位の最適化と全体整合性をどう両立するか マイクロサービスアーキテクチャを採用するメガベンチャーにおいて、各チームが自律的に開発を進める「サービス単位の最適化」は、リリースの迅速性を担保する上で極めて重要です。 しかし、個別の自由度を高めすぎると、組織全体の品質にばらつきが生じ、サービスを跨ぐ際の一貫性が失われるリスクがあります。 これを防ぐためには、各チームの裁量を尊重しつつも、組織全体で遵守すべき「品質のガードレール」を設ける設計が求められます。 具体的には、インターフェース設計やデータ整合性に関する最低限の共通ルールを定義し、それを自動化されたパイプラインで検証する仕組みを整えます。 QAマネージャーは、個別の機能テストには深く関与せず、サービス間を繋ぐハブとしての品質戦略に注力すべきです。 各チームが自律的に動ける範囲を明確にしつつ、全体のアーキテクチャに基づいた統合的なテスト方針を提示することで、スピードと信頼性の両立が可能になります。 連携部分で起きやすい不具合を防ぐ考え方 マイクロサービスや複数プロダクトが連携するシステムでは、個別のサービスは正常に動作していても、サービス間の通信やデータの受け渡し、外部APIの仕様変更に起因する不具合が頻発します。 こうした連携部分の不備を防ぐには、結合テストを待たずに各サービスの境界で検証を行う「コントラクトテスト」の導入が有効です。 提供側と利用側の間でインターフェースの仕様を合意し、その契約が守られているかを自動検証することで、他チームの変更による予期せぬ破壊を未然に防ぐことができます。 また大規模な環境では全てのサービスを同期させてテストすることが難しいため、スタブやモックを戦略的に活用し、依存関係を抽象化してテストを回す工夫も欠かせません。 物理的な接続に依存せず、論理的な整合性を早期に確認するアプローチへとシフトすることで、複数プロダクトが絡み合う複雑な環境でも、デプロイの心理的ハードルを下げ、手戻りの少ない開発サイクルを実現できます。 自動化を前提にした持続可能なテスト構造 急成長する組織において、手動テストをベースとした品質担保はすぐに限界を迎えます。 特に複数プロダクトを横断するプロジェクトでは、回帰テストの範囲が膨大になるため、自動化を前提としたテストピラミッドの再構築が不可欠です。 単体テストや統合テストといった低レイヤーの自動テストを開発チームが主体となって整備し、QA側はサービス間を跨ぐE2E（エンドツーエンド）テストなど、ユーザー体験に直結する高レイヤーの自動化に集中する体制を築きます。 ここで重要なのは、自動テスト自体がメンテナンスの負荷で形骸化しないよう、実行速度と安定性を考慮した設計にすることです。 不安定なテストを排除し、信頼性の高いテスト結果が常に得られる環境を整えることで、QA担当者は場当たり的な検証から解放され、より高度な品質改善施策に時間を割けるようになります。 持続可能な自動化は、属人化を防ぐだけでなく、組織が拡大しても品質が劣化しないための強力なインフラとして機能します。 機能軸だけでなく「性能・セキュリティ・安定性」など観点軸で整理する方法 大規模プロジェクトにおける品質保証は、画面上の機能が正しく動くかという「機能軸」だけでは不十分です。 メガベンチャーが抱える膨大なトラフィックや複雑なシステム構成を考慮すると、性能、セキュリティ、アクセシビリティ、耐障害性といった「非機能要件」をどう管理するかが事業の継続性を左右します。 これらの観点は各チームに任せきりにすると対応が後手に回りがちなため、QAマネージャーが中心となり、組織共通の「品質特性マップ」を作成して評価観点を整理することが有効です。 例えば、パフォーマンスであれば「APIの応答速度はこの閾値を維持する」、セキュリティであれば「このスキャンツールをCI/CDに組み込む」といった具体的な評価基準を観点ごとに定義します。 これにより、個別のプロダクト開発においても、重要な非機能的品質が見落とされるリスクを低減できます。 機能的な動作だけでなく、システムとしての堅牢性や信頼性を多角的に捉える視点を持つことで、経営層に対しても品質の価値を論理的に説明しやすくなります。 組織を動かすテスト管理の仕組みと可視化 テスト状況を経営と現場の両方に伝わる形で見せる方法 大規模プロジェクトにおいて、テストの進捗や品質状況を報告する際、相手の立場に合わせて情報を抽象化・具体化する視点が欠かせません。 経営層やビジネスサイドに対しては、細かなバグの数よりも「リリースに向けたリスクの残存状況」や「事業への影響度」を軸に報告を行います。 例えば重要機能のテスト完了率や、サービス停止に直結する致命的な不具合の収束傾向など、意思決定に直結する指標をダッシュボード化して提示することが有効です。 一方で、開発現場に対しては、どのモジュールに不具合が集中しているかといった具体的なボトルネックを可視化し、即座にアクションへ繋げられる情報を提供します。 このように、受け手の関心事に合わせて情報の解像度を調整することで、QAからの報告が単なる事務連絡ではなく、組織全体が共通の危機感や期待感を持って動くための判断材料へと進化します。 テストケース・不具合・進捗を横断的に管理する仕組み 複数プロダクトが並行して動くメガベンチャーでは、Excelやスプレッドシートによる個別のテスト管理は限界を迎えます。 情報のサイロ化を防ぎ、リアルタイムで全体像を把握するためには、テスト管理専用ツール（TMS）とBTS（不具合管理システム）を密接に連携させた横断的な管理基盤が必要です。 テストケースと不具合、そしてそれに関連する要件やコードの変更履歴を紐付ける「トレーサビリティ」を確保することで、ある不具合がどの機能に影響し、どのテストで検知されたのかを一目で追跡できるようにします。 また進捗状況をチームを跨いで共通のフォーマットで自動集計する仕組みを導入すれば、マネージャーが各チームに状況を確認して回る工数を削減でき、異常値が発生した際の早期検知が可能になります。 ツールをハブとして情報を集約することが、属人性を排除した論理的なプロジェクト推進の基盤となります。 属人化を防ぐルールとドキュメント設計 QAマネージャーが現場の板挟みになりやすい要因の一つに、テスト設計や実施判断が「特定の担当者の経験値」に依存している点が挙げられます。 この属人化から脱却するためには、ドキュメントの記述ルールやテスト設計の手法を標準化し、誰が担当しても一定の品質を維持できる仕組みを構築しなければなりません。 具体的には、テストケースの粒度や記述スタイルを揃えるためのガイドラインを策定し、レビュープロセスをワークフローに組み込みます。 ただし、過度な文書化はスピードを損なうため、自動テストのコード自体を仕様書として機能させたり、Wikiなどのナレッジベースを活用して「なぜそのテストが必要なのか」という意図を言語化して残す工夫が重要です。 知見が個人ではなく組織に蓄積される状態を作ることで、メンバーの入れ替わりや組織拡大にも耐えうる、持続可能な品質体制を築くことができます。 品質指標を「開発の敵」ではなく「共通言語」に変える工夫 バグの数やテスト消化率といった指標は、扱い方を誤ると現場にプレッシャーを与え、開発チームとの対立を生む「敵」になってしまいます。 品質指標を生産的な「共通言語」に変えるためには、指標を「犯人探し」のためではなく、「プロセスの課題を可視化し、より良いプロダクトを共に作るための羅針盤」として定義し直す必要があります。 例えば不具合密度が高い領域を特定した際、それを開発者のスキル不足と捉えるのではなく、設計の複雑さや環境の不備を解消するための投資判断の根拠として活用します。 またQA側だけで指標を決めるのではなく、開発やPdMと「今、自分たちが追うべき健全な指標とは何か」を議論し、合意形成を行うプロセスそのものが重要です。 数値が持つ意味をチーム全体で共有し、改善の喜びを分かち合える文化を醸成することで、QAはボトルネックではなく、事業成長を共に牽引するパートナーとしての地位を確立できます。 QAが価値創出の中核になるためのロードマップ ボトルネック型QAからパートナー型QAへの転換 開発プロセスの最後に控えて不具合を指摘するだけの「ゲートキーパー」から脱却し、事業成長を共に推進する「品質パートナー」へと進化することが、メガベンチャーのQA組織には求められています。 これまでのQAは、リリースを止めるボトルネックとして扱われがちでしたが、上流工程から積極的に関与することで、仕様の考慮漏れや手戻りを未然に防ぐ価値提供が可能になります。 具体的には、PdMやエンジニアと同じ目線でプロダクトのロードマップを共有し、どの機能がユーザーにとって最優先の価値を持つのかを理解した上で、テスト戦略を最適化します。 不具合を見つけること自体を目的とするのではなく、いかに速く、かつ安全に価値を市場へ届けるかを追求する姿勢を示すことで、周囲からの信頼は確実に変わります。 守りの姿勢から一歩踏み出し、品質を武器に攻めの開発を支える存在へと視点を転換することが、価値創出の第一歩となります。 四半期単位で進める改善ステップの描き方 理想的な品質体制は一朝一夕には構築できないため、四半期（3ヶ月）を一つの区切りとした段階的なロードマップを描くことが現実的です。 最初の四半期では、現状の負債を可視化し、各チームでバラバラだった不具合管理やテスト報告のフォーマットを統一することに注力します。 次の四半期では、その基盤を元に共通の品質基準を導入し、特にリスクの高い領域へのテスト自動化を試験的に進めます。 さらにその次は、成功事例を横展開し、組織横断で品質データを自動集計できる仕組みを定着させるといった具合に、小さな成功を積み上げていきます。 四半期単位で明確な成果（マイルストーン）を設定することで、現場のメンバーは改善の実感を得やすくなり、経営層に対しても「今、品質組織がどこに向かっているのか」を論理的に説明しやすくなります。 場当たり的な対応を排し、計画に基づいた着実な進化を提示することが、持続可能な体制づくりに繋がります。 全体最適が機能しているかを測るチェックポイント 仕組みが形骸化していないか、全体最適が本当に事業に貢献しているかを確認するためのチェックポイントを設けることも重要です。 例えば「特定のチームだけでなく、組織全体で重大障害の発生件数が抑制されているか」「リリースサイクルが短縮され、かつ手戻りによる遅延が減っているか」といった指標が代表的です。 また数値だけでなく「QAが企画段階のミーティングに自然に呼ばれるようになっているか」といった現場の連携深さも、パートナー型QAへの移行を測る重要なサインとなります。 さらに、不具合が検知されるタイミングが、下流のテスト工程から上流の開発工程へとシフトしているか（シフトレフトの進捗）も確認すべき項目です。 これらのチェックポイントを定期的に振り返ることで、自らの判断や設計が正しい方向を向いているという確信を持つことができ、迷いなく次の一手を打つことが可能になります。 スピードと品質を両立し、経営と現場の両面から信頼される状態の実現方法 最終的に目指すべきは、QAの存在がプロダクトのスピードを加速させていると実感される状態です。 これを実現するためには、高度な自動化基盤の提供によってエンジニアが安心してコードを書ける環境を整える一方で、経営に対しては品質が事業の機会損失をどれだけ防いでいるかをデータで示し続ける必要があります。 現場の苦労と経営の期待という板挟みのストレスを、組織全体の品質ガバナンスを設計するという「やりがい」へと変換していくのです。 品質を「守るべきコスト」から「投資すべき競争力」へと定義し直すことで、QAマネージャーとしての評価は高まり、組織内での影響力も拡大します。 リリース速度を落とさずに品質を担保し続ける仕組みが動き出したとき、QAは単なる検査部門ではなく、メガベンチャーの急成長を支える最強のアクセルとして、現場と経営双方から絶対的な信頼を勝ち取ることになります。 まとめ 大規模プロジェクトにおけるテスト管理の要諦は、部分的な改善の積み上げではなく、全体を俯瞰した「仕組みの設計」にあります。 チーム横断の共通基準を設け、リスクに基づいた優先順位付けを行うこと。 そして、マイクロサービス間の境界をコントラクトテストや自動化で守り、品質指標を共通言語として組織に浸透させること。 これらの取り組みを通じて、QAは「リリースを止める存在」から「リリースを確信させる存在」へとその役割を変えていきます。 急成長フェーズにある組織の品質課題を解決するのは、容易なことではありません。 しかし、四半期単位で着実に改善のロードマップを歩み、属人性を排除した持続可能な体制を築くことができれば、QAは間違いなく事業成長の中核を担うアクセルとなります。 現場のスピード感を損なわず、かつ経営が求める信頼性を担保する。 その両立を実現したとき、QAマネージャーとしての価値は最大化され、組織全体に揺るぎない品質文化が根付くはずです。 まずは、今日からできる一歩として、組織全体の「品質のガードレール」を定義することから始めてみてはいかがでしょうか。 QA組織成熟度チェックリスト 各項目について、組織の状態が当てはまるか確認してください。 レベル1：場当たり的対応（属人化フェーズ） 　テストの実施が特定の担当者の経験や記憶に依存している。 　プロジェクトごとにテストケースのフォーマットや管理方法がバラバラである。 　不具合報告の基準が定義されておらず、起票漏れや情報の過不足が多い。 　リリース直前に予期せぬ不具合が発覚し、日常的に「火消し」が発生している。 レベル2：プロセス標準化（部分最適フェーズ） 　組織内で共通のテスト管理ツール（TMS）や不具合管理システム（BTS）が導入されている。 　テスト設計のガイドラインがあり、誰が書いても一定の粒度が保たれている。 　リグレッションテスト（回帰テスト）の範囲が定義され、定期的に実施されている。 　基本的な品質メトリクス（不具合件数、テスト消化率など）の集計が始まっている。 レベル3：戦略的QA（全体最適フェーズ） 　「品質基準」が明文化され、プロダクトのフェーズに応じて柔軟に適用されている。 　リスクベースドテスティングが導入され、事業インパクトに応じた強弱がついている。 　マイクロサービス間の連携など、プロダクト横断のテスト方針が合意されている。 　QAマネージャーが、プロジェクトの要件定義（企画段階）からレビューに参加している。 レベル4：自動化・継続的改善（効率化フェーズ） 　CI/CDパイプラインに自動テストが組み込まれ、デプロイごとに検証が走っている。 　テストピラミッドに基づき、ユニットテスト、APIテスト、E2Eテストが適切に配分されている。 　障害の振り返り（ポストモーテム）が定着し、再発防止策がプロセスに還元されている。 　非機能要件（性能・セキュリティなど）の評価が仕組みとして組み込まれている。 レベル5：ビジネスパートナー（価値創出フェーズ） 　品質指標が「開発の敵」ではなく、経営・PdM・開発の「共通言語」になっている。 　QAの活動が、リリースの高速化とユーザー満足度の向上に直結していると社内で認識されている。 　蓄積された品質データから、将来の不具合発生リスクを予測・予防できている。 　QA組織が事業戦略の一部として、品質の観点から新機能の提案や改善を行っている。 チェック後のアクション案 レベル1〜2が中心の場合： まずは「負債の可視化」と「フォーマットの統一」を四半期目標に設定し、属人化の解消を目指します。 レベル3が中心の場合： 共通基準を武器に、開発・PdMを巻き込んだ「シフトレフト」の体制構築に注力します。 レベル4以上の場合： QAの成果を「事業利益（機会損失の防止やリリース速度の向上）」として数値化し、経営層へのプレゼンスを高めるフェーズです。 QA業務効率化ならPractiTest テスト管理の効率化 についてお悩みではありませんか？そんなときはテスト資産の一元管理をすることで 工数を20%削減できる 総合テスト管理ツール「 PractiTest 」がおすすめです！ PractiTest (プラクティテスト) に関する お問い合わせ トライアルアカウントお申し込みや、製品デモの依頼、 機能についての問い合わせなどお気軽にお問い合わせください。 お問い合わせ この記事の監修 Dr.T。テストエンジニア。 PractiTestエバンジェリスト。 大学卒業後、外車純正Navi開発のテストエンジニアとしてキャリアをスタート。DTVチューナ開発会社、第三者検証会社等、数々のプロダクトの検証業務に従事。 2017年株式会社モンテカンポへ入社し、マネージメント業務の傍ら、自らもテストエンジニアとしテストコンサルやPractiTestの導入サポートなどを担当している。 記事制作： 川上サトシ （マーケター、合同会社ぎあはーと代表）

.entry-content ul > li > ul { display: none; } tr td:first-child { white-space: nowrap; } .nowrap2+table tr td:nth-child(2) { white-space: nowrap; } td { text-align: left !important; } 目次 目次 はじめに この記事の対象読者 背景・課題 背景 課題 AI駆動開発ワークフローの概要 AIサービスごとの役割 Devin Playbook ユーザー起動のPlaybook（Slack → Devin） !ai_task（単一タスク実装） !ai_tasks（タスク分割＆並列実装） !human_review（人間承認フロー） 人間レビューが必要なケース ワークフロー自動呼び出しのPlaybook !fix_ci_failure（CI失敗時の自動修正） !fix_review_comments（レビュー指摘の自動修正） !context_curation（AIコンテキストの週次更新） 使用技術 機能一覧 アーキテクチャ SlackからPR承認までの完全フロー 2つのワークフローの役割 フロー別の使い分け 実装 設定ファイル AI Task Implementation：Issueから実装までの自動化 AI Task Dispatcher（ゲートウェイ） 実装ワークフローの動作 ラベルによる動作の分岐 重複実行の防止の仕組み キャンセル時のクリーンアップ AI Review Orchestrator：レビューから承認までの自動化 レビュー・ワークフローの動作 統合レビュー・修正ループの詳細フロー ジョブ構成と責務 Phase 1: Gate（スキップ判定） Phase 2: Perspective Router（ハイブリッド分類方式） 分類フロー 事前分類ルール Phase 3: CI完了待機 CI完了を待つ理由 Phase 4: Claude Review Perspectiveラベルに基づくレビュー レビュープロンプトの構造 分類判定ルール 自動承認の対象外となる変更タイプ 指摘の重大度とblockingフラグ（Conventional Comments準拠） PR説明文の自動生成・更新 関連 Issue の自動取得 PRタイトル・説明文の自動生成 タイトル生成ルール Phase 5: Devin自動修正 Devin修正の種類 修正ループの詳細 ループカウントの管理 Perspectiveラベルの更新ルール ループ終了条件 自動承認の条件 データ連携方式 Claude → Devinのデータ渡し 構造化出力スキーマ 技術的なポイント 1. concurrencyによる並行実行の制御 2. Devinセッションの自動停止 trapハンドラー（即時対応） if: cancelled()バックアップステップ GitHub Actionsのキャンセルシーケンス 3. AWS BedrockによるClaude呼び出し 4. マクロ形式によるプロンプト管理 5. HEAD SHAの検証 使い方 AI Task Implementationの使い方（Slack → Issue → 実装） 起動方法 注意点 AI Review Orchestratorの使い方（PR → レビュー → 承認） 自動レビューの流れ Claudeへの質問・修正依頼 操作手順まとめ 導入効果 定量的な効果 定性的な効果 Renovate PRの自動レビュー・承認 自動承認の条件 AI開発の効果測定（週次レポート） 計測される KPI レポート例 AIコンテキストの自動育成 動作フロー 更新対象ファイル ドキュメントの階層構造 各ディレクトリの役割 残っている課題 運用上の注意点 スキップラベルの活用 人間のレビューが必要なケース ワークフロー別ラベル操作 トラブルシューティング まとめ 実現した効果 重要なポイント 今後の展望 最後に 参考リンク はじめに こんにちは、新規事業部 マネジメントポータルブロックの岡本です。 「PRを作ったけど、レビューまで時間がかかる」「忙しいときレビューが後回しになる」──この悩み、開発者なら誰もが経験したことがあるのではないでしょうか。 私たちのチームでは、ClaudeとDevinを組み合わせたAI駆動開発ワークフローを導入し、レビュー待ち時間ゼロ・CIエラーの自動修正・Issueからの即時の実装開始を実現しました。この記事では、その設計思想から実装詳細、導入効果までを解説します。 この記事の対象読者 GitHub Actionsを使ったCI/CDの経験がある方 AIコーディングアシスタント（Claude、Devinなど）に興味がある方 チーム開発の効率化を検討している開発リーダー・マネージャー 背景・課題 背景 私たちのチームはZOZOマッチ管理画面を少人数で運用しており、各メンバーがフロントエンド・バックエンド・LP作成と複数の領域を担当しています。そのため、コンテキストスイッチが頻繁に発生し、「PRを作成したが、レビュアーが別タスクに集中している」「CIエラーを修正しようとしたら、他の緊急対応が入った」といった状況が日常的に起きていました。 結果として、レビューやCI修正の待ち時間が発生しやすく、開発のリズムが途切れがちでした。そこで、「人間は創造的な作業に集中し、定型的な作業はAIに任せる」という方針のもと、Claude（レビュー・判断）とDevin（実装・修正）を組み合わせたワークフローを整備しました。 課題 従来の開発フローでは、次のような課題がありました。 課題 詳細 レビュー待ち時間 PR作成から人間のレビューまでに数時間〜1日かかることがあった レビュー品質のばらつき レビュアーの経験や専門分野によって指摘内容に差があった Issue着手の遅延 Issueが起票されてから実装開始まで時間がかかっていた ライブラリ更新の負担 Renovateが作成する大量の依存関係の更新PRのレビュー・マージ作業が開発者の負担になっていた これらの課題を解決するため、2つのGitHub Actionsワークフローを中心に自動化を構築しました。 AI駆動開発ワークフローの概要 AIサービスごとの役割 このワークフローでは、2つのAIサービスを組み合わせて活用しています。GitHub Actionsとの連携における実行方式の違いから、次のように役割を分けています。 Devin（実装・修正）：Issueの実装、CIエラー修正、レビュー指摘の修正を担当。非同期でセッションを開始し、修正完了まで一貫した作業が可能。ブランチ操作からコミット・プッシュまでを単一セッションで実行でき、修正完了後にPRが更新されてワークフローが再トリガーされる設計とも相性が良い Claude Code（レビュー・判断）：PRのレビュー、分類判定、自動承認の判断を担当。同期的に結果を返すため、「自動承認 / 人間レビュー依頼 / Devin修正起動」の分岐処理を同一ワークフロー内で完結できる。構造化出力（JSONスキーマ）により、後続の処理時に扱いやすい形式でレビュー結果を取得できる Devin Playbook Playbookは、Devinに対する再利用可能な指示セットです。タスクの種類に応じた判断ロジック（セキュリティチェック、タスクサイズ判定など）、GitHub連携処理、エラーハンドリングが定義されており、一貫した品質でタスクを実行できます。 Playbookには、Slackからユーザーが起動するものと、GitHub Actionsワークフローが自動呼び出しするものの2種類があります。今回作成したワークフローでは、Devin APIを使用し、macro形式（macro IDとpayloadをJSONで渡す）でPlaybookを呼び出しています。 ユーザー起動のPlaybook（Slack → Devin） Slackで @devin をメンションし、 ! で始まるコマンドを送信すると、対応するPlaybookが実行されます。 コマンド 用途 対象タスク !ai_task 単一タスク実装 Small〜Medium（半日以内） !ai_tasks タスク分割＆並列実装 Large（1日以上、複数コンポーネント） !human_review 人間承認フロー セキュリティ関連、要確認タスク !ai_task （単一タスク実装） 指定されたタスクを直接実装し、PRを作成します。 !ai_tasks （タスク分割＆並列実装） 複雑なタスクを分析し、最大5つのsub-issueに分割して並列実装します。 !human_review （人間承認フロー） セキュリティ関連や重要な変更など、人間の確認が必要なタスク向けです。 人間レビューが必要なケース 認証・認可の変更 個人情報（PII）の扱い シークレット・APIキーの変更 ビジネスロジックの大幅な変更 本番環境への影響が大きい変更 ワークフロー自動呼び出しのPlaybook 次のPlaybookはGitHub Actionsワークフローから自動的に呼び出されます。ユーザーが直接実行することはありません。 Playbook 用途 呼び出し元 !fix_ci_failure CI失敗時の自動修正 ai-review-orchestrator.yml （CI失敗時） !fix_review_comments レビュー指摘の自動修正 ai-review-orchestrator.yml （blockingの指摘があるとき） !context_curation AIコンテキストの週次更新 devin-context-refresh.yml （毎週月曜09:00 JST） !fix_ci_failure （CI失敗時の自動修正） CI（Lint、Typecheck、Test）が失敗したPRを自動修正します。 GitHub ActionsのCIログを解析してエラーを特定 エラー種別に応じて修正（Lint → pnpm run lint:fix 、Type → 型エラー修正、Test → テスト更新） 修正をコミット・プッシュしてセッション終了 ビジネスロジックの変更が必要な場合は修正せず人間にエスカレーション !fix_review_comments （レビュー指摘の自動修正） Claude Reviewからの指摘（ blocking: true ）を自動修正します。 Blocker / Major の指摘を必須の修正対象として処理 各指摘の suggestion に従って修正 修正をコミット・プッシュしてセッション終了 認証・認可に関わる変更は修正せず人間にエスカレーション !context_curation （AIコンテキストの週次更新） PRコメントから学習可能な知見を抽出し、AI関連ドキュメントを週次で自動更新します。 直近7日間のPRコメント（Bot除外）を収集 コメントから有用な変更点、落とし穴、ルール例外、命名・設計ガイドラインを抽出 AGENTS.md 、 docs/ai-context/ 、 docs/guidelines/ 、 docs/review-perspectives/ を更新 更新内容をPRとして作成（人間がレビュー・マージ） 使用技術 ワークフローは、次の技術・サービスを組み合わせて構成しています（ワークフロー上の使用順）。 技術・サービス 用途 Slack タスク起点のオペレーション（Devinへの指示） GitHub Issues/PR/Labels 進行管理とトリガー Devin API Issueの実装・CIエラー修正・レビュー指摘の修正 GitHub Actions ワークフロー実行（CI待機、ジョブ分岐、通知） AWS Bedrock Claude実行基盤（セキュリティ要件対応） Claude Code Action PRレビュー実行・分類判定・自動承認 機能一覧 機能 内容 主な効果 AI Task Implementation Slack/ラベル起点で Devinが実装しPRを作成 Issue着手の即時化 AI Review Orchestrator Claudeがレビューし、Devinが修正 レビュー待ちの解消と品質の均一化 CI自動修正 CI失敗時にDevinが修正を実行（最大3回） 手戻り削減 自動承認 AI_ONLYかつ指摘なしで自動承認 PR処理の高速化 週次メトリクス KPIを週次で自動計測しIssue化 効果測定の継続 ナレッジ更新 PRコメントからドキュメントを自動更新 レビュー品質の継続改善 アーキテクチャ SlackからPR承認までの完全フロー 2つのワークフローの役割 ワークフロー トリガー 役割 AI Task Implementation Issueに ai-task / ai-tasks ラベル追加 DevinがIssueの実装を担当し、PRを作成 AI Review Orchestrator PRの作成・更新 Claudeがレビュー、Devinが修正、条件を満たせば自動承認 フロー別の使い分け 各Playbookの詳細なフローは「 Devin Playbook 」セクションを参照してください。 シナリオ Slack コマンド 処理フロー 単一タスク（直接の実装が可能） @devin !ai_task タスク説明 Devin → Issue + PR → 自動レビュー → 承認 複雑なタスク（分割が必要） @devin !ai_tasks タスク説明 Devin → 親 Issue + sub-issue → 並列実装 → 自動レビュー 要承認タスク @devin !human_review タスク説明 Devin → Issue 作成 → 人間承認 → 自動実装 Claudeに質問・修正依頼 @znm-claude-code 依頼内容 Claudeが対応（PR/Issueコメント） 実装 設定ファイル ワークフローはGitHub Actionsの設定ファイルで定義しています。主要ファイルと役割は次のとおりです。 ファイル 役割 .github/workflows/ai-task-dispatcher.yml Issueラベル検知・条件判定のゲートウェイ（条件を満たす場合のみimplementationを起動） .github/workflows/ai-task-implementation.yml DevinによるIssue実装（dispatcher から呼び出し） .github/workflows/ai-review-orchestrator.yml PRレビュー・修正ループ・Renovate統合 .github/workflows/pr-perspective-router.yml Perspectiveラベルの再分類 .github/workflows/ai-renovate-review.yml Renovate PRの依存関係レビュー（orchestrator から呼び出し） .github/workflows/ai-metrics-report.yml 週次メトリクス生成 .github/workflows/devin-context-refresh.yml コンテキスト更新 AI Task Implementation：Issueから実装までの自動化 AI Task Dispatcher（ゲートウェイ） ai-task-dispatcher.yml は、Issueのラベル追加を検知し、条件を満たす場合のみ実装ワークフローを起動するゲートウェイです。 Dispatcherを分離している理由は3つあります。 条件判定の一元化：ラベル検知と条件チェックを単一ファイルに集約し、保守性を向上 不要なワークフロー発火の防止：条件を満たさない場合は早期終了し、リソースを節約 責務の分離：「いつ起動するか」（dispatcher）と「何をするか」（implementation）を明確に分離 実装ワークフローの動作 ai-task または ai-tasks ラベルがIssueに追加されると、dispatcher経由でDevinが自動的に実装を開始します。トリガー条件は次のとおりです。 Issueの labeled イベントで起動（dispatcherが検知） ai-task / ai-tasks ラベル付与時のみ対象 in-progress が付いていない場合だけ開始 起点は2パターンあります。 Playbook起動（Slackなど）：PlaybookがIssueを作成 → ai-task / ai-tasks を付与 → このワークフローが起動 既存Issue起点：このワークフローが skip_issue_creation: true を渡してPlaybookを実行（Issue作成はスキップ） ラベルによる動作の分岐 ラベルに応じて対応するPlaybookが実行されます。各Playbookの詳細なフロー（セキュリティチェック、タスクサイズ判定、実装手順など）は「 Devin Playbook 」セクションを参照してください。 ラベル Playbook 動作 ai-task !ai_task 単一タスクとして実装 ai-tasks !ai_tasks タスク分割 → 並列実装 sub-issue作成には gh sub-issue 拡張が必要です（Playbook側 or Devinのリポジトリ初期設定で事前インストール）。 重複実行の防止の仕組み 同じIssueに対する重複実行を防ぐため、concurrency設定でIssue番号単位の同時実行を1つに制御し、進行中の実行があれば新しい実行でキャンセルします。 例えば、同じIssueに短時間でラベル追加が続いた場合、 labeled イベントが複数回発火します。この二重起動を防止します。 キャンセル時のクリーンアップ ワークフローがキャンセルされた場合、次のクリーンアップ処理を実行します。 キャンセル時にDevinセッションを停止 キャンセル時に in-progress ラベルを削除して再実行可能にする 失敗時も in-progress ラベルを削除して再実行可能にする AI Review Orchestrator：レビューから承認までの自動化 レビュー・ワークフローの動作 PRが作成・更新されると、 ai-review-orchestrator.yml が自動実行されます。このワークフローはPRの作成・更新をトリガーに発火し、PRの作成元は問いません。 AI Task Implementation経由のPR: DevinがPR作成 → このワークフローが発火 手動作成されたPR: 開発者の直接PR作成 → このワークフローが発火 なお、 ai-task-dispatcher.yml とこのワークフローは独立しており、直接の呼び出し関係はありません。 統合レビュー・修正ループの詳細フロー ジョブ構成と責務 ai-review-orchestrator.ymlは約1,500行の大規模ワークフローです。6つのフェーズに分かれています。 フェーズ ジョブ名 責務 依存関係 1 gate スキップ判定、PR情報取得、イテレーション管理 なし 2 perspective-router PR分類、perspective:* ラベル付与（初回のみ、Renovate以外） gate 3 wait-for-ci CI完了待機（最大20分、30秒間隔ポーリング） gate, perspective-router 4a devin-ci-fix CI失敗時のDevin自動修正 gate, wait-for-ci (CI失敗時) 4b-1 renovate-review Renovate PR専用のClaude依存関係レビュー（ ai-renovate-review.yml 呼び出し） gate, wait-for-ci (CI成功かつRenovate PR時) 4b-2 claude-review CI成功/未検出時のClaudeレビュー実行（Renovate以外） gate, wait-for-ci (CI成功/未検出時) 4c devin-review-fix レビュー指摘ありの場合のDevin自動修正 gate, claude-review (指摘あり時) 4d auto-approve AI_ONLY + 指摘なしの場合の自動承認 gate, claude-review or renovate-review 4e needs-human-review NEEDS_HUMAN + 指摘なしの場合の人間レビュー依頼 gate, claude-review or renovate-review 4f vrt Visual Regression Testingの実行 auto-approve or needs-human-review 5 max-iterations-reached イテレーション上限到達時の通知 gate 6 ci-timeout CI待機タイムアウト時の通知 gate, wait-for-ci Phase 1: Gate（スキップ判定） 次の条件でワークフローをスキップします。 条件 判定方法 理由 Draft PR pull_request.draft == true 作業中のためレビュー不要 Bot作成PR（Devin・Renovate 以外） actor がbotかつDevin・Renovateでない 無限ループ防止 Fork PR pull_request.head.repo.fork == true シークレット/権限制約のためスキップ skip-ai-review ラベル ラベル存在チェック 明示的スキップ Renovate PR actor が renovate[bot] Renovate専用レビュー（ renovate-review ）へルーティング ai-auto-approved ラベル ラベル存在チェック 既に承認済み また、新しいpushがあった場合はAI関連ラベルを削除し、承認を取り消して再レビューします。ラベルの削除ルールはpush元によって異なります。 人間のpush： ai-auto-approved / needs-human-review / perspective:* を削除して再分類 Botのpush： ai-auto-approved / needs-human-review のみ削除して分類は維持 Phase 2: Perspective Router（ハイブリッド分類方式） PRの変更内容を分析し、適切なレビュー観点を決定します。キーワードベースの事前分類 + Claudeフォールバックのハイブリッド方式を採用しています。 分類フロー 事前分類ルール ラベル パスパターン キーワード perspective:workflow .github/workflows/ , .github/actions/ , action.yml workflow, ci, cd, pipeline, jobs, steps, runs-on perspective:security auth/ , login/ , session/ auth, token, secret, credential, password, encrypt, sanitize, xss, csrf, pii, vulnerability perspective:quality *.test.* , *.spec.* , __tests__/ , eslint , prettier , tsconfig test, spec, lint, format, accessibility, a11y, aria-, vitest, jest perspective:dependency package.json , pnpm-lock.yaml , yarn.lock , package-lock.json dependency, package, version, upgrade, license perspective:api /api/ , openapi , swagger , schema , .dto. api, endpoint, schema, openapi, graphql, rest perspective:perf （パスパターンなし） performance, optimize, cache, lazy, memo, bundle, split, prefetch perspective:business domain/ , business/ permission, role, billing, payment, validation, status, transition, rule perspective:general 上記に該当しない場合のみ - 複数パターンにマッチした場合、該当ラベルがすべて付与されます。 perspective:general は他のラベルと併用されません。 Phase 3: CI完了待機 他のCIジョブ（型チェック、lint、テストなど）の完了を待機します。待機の仕組みは次のとおりです。 自分自身のワークフローやVRTは待機対象から除外 部分一致の除外パターンも併用して精度を上げる 最大20分、30秒間隔でポーリング CI Runが一定時間見つからない場合（約5分）は ci_status=skipped としてClaudeレビューへ進みます。 success / neutral / skipped は成功扱いです。 CI完了を待つ理由 CIが失敗している状態でレビューしても意味がない CI失敗 → Devin修正 → またCI失敗 → またレビュー... という無駄なループを防ぐ CIが通った状態のコードに対してレビューすることで、品質の高いフィードバックが可能 Phase 4: Claude Review Claude Code Actionを使用して、PRを包括的にレビューします。 Perspectiveラベルに基づくレビュー Claude Reviewでは、Phase 2で付与された perspective:* ラベルに応じて、対応するレビュー観点ドキュメントを動的に読み込みます。 ラベル 対応ファイル 主なレビュー観点 perspective:workflow docs/review-perspectives/workflow.md GitHub Actions/CI/CD の設計・セキュリティ perspective:security docs/review-perspectives/security.md 認証・認可・入力検証・機密情報の管理 perspective:quality docs/review-perspectives/quality.md テスト・Lint・アクセシビリティ perspective:dependency docs/review-perspectives/dependency.md 依存関係の追加・更新・削除 perspective:api docs/review-perspectives/api.md API設計・スキーマ・エラーハンドリング perspective:perf docs/review-perspectives/perf.md パフォーマンス・キャッシュ・最適化 perspective:business docs/review-perspectives/business.md ビジネスロジック・権限・バリデーション perspective:general docs/review-perspectives/general.md 汎用的なコード品質（他に該当しない場合） レビュー実行時の読み込みフローは次のとおりです。 PRから perspective:* ラベル一覧を取得 対応する docs/review-perspectives/*.md を読み込み 取得内容をプロンプトに差し込みレビュー実行 たとえば、セキュリティ関連のPRには security.md の観点が、API関連のPRには api.md の観点が適用されるといった具合です。 レビュープロンプトの構造 レビュープロンプトは次のルールで構成されます。 Bedrock経由でClaudeを実行 Perspective指定と重大度定義をプロンプトに含める Blocker/Majorを blocking: true として扱う 分類判定ルール 判定 条件 自動承認 AI_ONLY テストコード、型定義、明確なバグ修正、リファクタリング 可能 NEEDS_HUMAN ドキュメント、スタイル、設定ファイル、セキュリティ関連 不可 自動承認の対象外となる変更タイプ 次の変更は必ず人間のレビューが必要です（ NEEDS_HUMAN と判定）。 ドキュメント更新：README.md, *.mdファイル、docs/配下の変更 スタイル調整：CSS, Tailwindクラス、デザイン・レイアウト変更 設定ファイル変更：tsconfig, eslint, prettier, vite.config等 指摘の重大度とblockingフラグ（Conventional Comments準拠） 重大度 blocking 意味 修正要否 [Blocker] true 必ず修正が必要 必須 [Major] true 強く推奨される修正 必須 [Minor] false 推奨される改善 任意 [Nit] false 微細な指摘（スタイル等） 任意 [Question] false 仕様・意図の確認質問 回答必須（修正不要） [Praise] false 良いコードへの称賛 対応不要 blocking: true の指摘が1件以上あると、Devin自動修正が実行されます。 PR説明文の自動生成・更新 Claude Reviewでは、レビュー結果と同時にPR説明文を自動生成・更新する機能があります。 関連 Issue の自動取得 PR本文からclosing keywords（ Closes #123 , Fixes #456 など）を自動的に抽出し、関連Issueを特定します。抽出されたIssue番号はレビュープロンプトに含まれ、Claudeが変更の意図を理解する際のコンテキストとして活用されます。 PRタイトル・説明文の自動生成 ClaudeはPR内の全てのコミットと変更ファイルを分析し、次の手順でタイトルと説明文を自動生成します。 PR内の全コミット一覧を取得（最大50件） 全ての変更ファイルを分析 PR全体を代表するタイトルを日本語で生成（Conventional Commits形式） .github/PULL_REQUEST_TEMPLATE.md に沿って説明文を生成 タイトル生成ルール 形式： {prefix}: {変更内容の要約} （例： feat: ユーザー認証機能の追加 ） prefix：feat / fix / docs / refactor / chore / testから変更種別に応じて選択 50文字以内で簡潔に日本語で記載 複数の変更がある場合は、主要な変更を代表するタイトルに 生成されたタイトルと説明文は、レビュー完了後に自動的にPRへ反映されます（それぞれ生成された場合のみ更新）。PR作成者がタイトルや説明文を適切に書けなかった場合でも、Claudeが内容を自動生成してくれます。最新のコミットだけでなくPRに含まれる全てのコミットを考慮するため、複数回のpushがあっても正確な内容が生成されます。 Phase 5: Devin自動修正 Claudeのレビューで指摘があった場合、またはCIが失敗した場合、Devinが自動修正します。 Devin修正の種類 ジョブ名 用途 参照 Playbook devin-ci-fix CI失敗の修正（CIログを解析して自動修正） fix-ci-failure.devin.md devin-review-fix レビュー指摘の修正（Claudeの指摘に基づいて自動修正） fix-review-comments.devin.md Devinへの修正指示は次の手順で行います。 blocking: true の指摘だけを抽出し、抽出結果をmacro payloadに組み込んでDevinに送信します。 修正ループの詳細 ループカウントの管理 イテレーションはCI修正 + レビュー修正の合計回数でカウントします。 Push種別 カウント動作 理由 人間がPR作成 0からスタート 新規PR Devinがpush カウント継続 自動修正ループ中 人間が修正push 0にリセット 人間の修正後は新規扱い 上限（3回）に達した後でも、人間が修正してpushすればカウントがリセットされ、レビューが再開されます。 Perspectiveラベルの更新ルール Push種別 Perspective Router ラベル動作 人間がPR作成 ✅ 実行 新規ラベル付与 Devinがpush ❌ スキップ 既存ラベル維持 人間が修正push ✅ 実行 既存ラベル削除 → 再分類 ループ終了条件 正常終了：CI成功 + レビュー指摘なし → 自動承認 上限到達： iteration_count >= MAX_ITERATIONS → 人間レビュー依頼 タイムアウト：CI待機が20分超過 → 人間への確認依頼 自動承認の条件 次のすべてを満たした場合のみ自動承認されます。 CI成功 Claudeレビュー完了 分類が AI_ONLY blockingな指摘がない HEAD SHAが変更されていない（レース条件対策） データ連携方式 Claude → Devinのデータ渡し Claudeのレビュー結果をDevinに渡す方式は、ジョブ出力による直接連携を採用しています。 構造化出力スキーマ Claudeに --json-schema オプションでレビュー結果の構造を指定し、次の項目を必須にしています。 classification （AI_ONLY / NEEDS_HUMAN） Blocker/Major/Minorの件数フラグとカウント fix_instructions （修正指示文） issues （指摘一覧：severity / blocking / file / messageなど） 技術的なポイント 1. concurrencyによる並行実行の制御 同一PRに対して1つのワークフローのみ実行（ group で制御） cancel-in-progress: true のため、Devinが修正をpushした場合： 新しいワークフローが開始される 古いワークフローは自動的にキャンセルされる Devinセッションはtrapハンドラーにより自動停止される 新しいワークフローはCI完了を待機してからレビュー 2. Devinセッションの自動停止 ワークフローがキャンセルされた際、実行中のDevinセッションを確実に停止するため、二重のセーフティネットを実装しています。 trapハンドラー（即時対応） Devin API呼び出し中にシグナル（SIGINT/SIGTERM）を受信した場合、trapハンドラーが即座にセッションを停止します。SIGINT/SIGTERMを受けると即座にcleanupを実行し、 /tmp/devin_resp.json から session_id を取得して10秒以内にセッションを終了します。 if: cancelled() バックアップステップ API呼び出しが完了してからキャンセルされた場合に備えて、専用のクリーンアップステップを用意しています。 outputs または /tmp/devin_resp.json から session_id を取得してセッションを停止します。 GitHub Actionsのキャンセルシーケンス GitHub Actionsはキャンセル時に次の順序でシグナルを送信します。 SIGINT 送信 → 7.5秒待機 SIGTERM 送信 → 2.5秒待機 強制終了 trapハンドラーは最初の SIGINT でcleanupを実行するため、最大10秒の猶予内でDevinセッションを停止できます。 3. AWS BedrockによるClaude呼び出し セキュリティ要件を満たすため、Claude APIではなくAWS Bedrock経由でClaudeを呼び出しています。AWS認証情報を設定し、Claude Code Actionの use_bedrock を有効化しています。 設定項目 値 リージョン us-east-1 IAMロール <your-bedrock-access-role> モデル（レビュー） Claude（Bedrock Application Inference Profile） モデル（分類） Claude Haiku（ anthropic.claude-3-haiku-20240307-v1:0 ） 4. マクロ形式によるプロンプト管理 Devinへの指示は、macro IDとpayloadをJSONとして渡すマクロ形式で標準化しています。Playbookのmacro IDと一対一で対応しており、一貫性のある指示が可能です。 5. HEAD SHAの検証 レース条件を防ぐため、承認前にHEAD SHAが変更されていないことを確認しています。実行開始時のHEAD SHAと現在のSHAを比較し、一致しない場合は自動承認をスキップします。 使い方 AI Task Implementationの使い方（Slack → Issue → 実装） SlackからDevinにタスクを依頼すると、Issue作成から実装、PR作成までを自動で行います。各Playbookの詳細なフローは「 Devin Playbook 」セクションを参照してください。 起動方法 方法 手順 動作 Slackから（推奨） @devin !ai_taskタスク説明 DevinがIssue作成 → ai-task ラベル付与 → ai-task-dispatcher.yml 発火 → 実装開始 Slackから（複雑なタスク） @devin !ai_tasksタスク説明 Devinが親Issue作成 → sub-issueに分割 → 並列実装 GitHub Issueから Issue に ai-task / ai-tasks ラベルを付与 ai-task-dispatcher.yml 発火 → 実装開始 注意点 in-progress ラベルがあるIssueはスキップされます（実装中のため） セキュリティ関連を検出した場合、 !human_review への切り替えを案内してセッション終了 タスクサイズが合わない場合、適切なPlaybookへの切り替えを案内してセッション終了 AI Review Orchestratorの使い方（PR → レビュー → 承認） PRが作成・更新されると、 ai-review-orchestrator.yml が自動起動し、Claudeがレビューします。 自動レビューの流れ CI完了待機（最大20分） Perspective分類（初回のみ、変更内容に応じてラベル付与） Claudeレビュー（Perspectiveに基づく観点でレビュー） 結果に応じた分岐： 指摘あり → Devin自動修正（最大3回） AI_ONLY + 指摘なし → 自動承認 NEEDS_HUMAN → 人間レビュー依頼 Claudeへの質問・修正依頼 PRやIssueに対してClaudeに質問や修正依頼をしたい場合は、 @znm-claude-code をメンションしてコメントします。 操作手順まとめ 入口を選ぶ。 @devin !ai_task （単一タスク）/ @devin !ai_tasks （分割タスク）/ @devin !human_review （人間の承認が前提）。Slackを使わない場合はIssueにラベルを付与する DevinがIssue/PRを作成し、 ai-review-orchestrator.yml が自動起動する CI完了後にClaudeがレビューし、指摘があればDevinが修正する（最大3回） AI_ONLY かつ指摘なしなら自動承認、 NEEDS_HUMAN は人間レビューへ。Claudeへの質問や修正依頼は @znm-claude-code を利用する 運用上の例外（ skip-ai-review / renovate など）は「運用上の注意点」を参照してください。 導入効果 定量的な効果 指標 導入前 導入後 PR作成からレビュー開始まで 平均4時間 即時 CIエラー修正時間 平均30分/回 自動 単純なIssueの実装開始 平均1日 即時 RenovatePRの処理 手動確認・マージ 依存関係レビュー後に自動承認 定性的な効果 開発者が集中する時間の確保 定型的なエラー修正から解放され、創造的な作業に集中できるようになった レビュー品質の均一化 Perspectiveに基づくレビューで、一貫した品質のレビューが実現した レビュアーの経験や専門分野に依存しない指摘が可能になった 心理的安全性の向上 AIが最初にレビューすることで、人間のレビューでの「些細な指摘」が減った レビュアーは本質的な議論へ集中できるようになった ナレッジの蓄積 レビュー観点ドキュメント（ docs/review-perspectives/ ）が知識ベースとして機能 新しいメンバーのオンボーディングにも活用できる ライブラリ更新の自動化 Renovateが作成する依存関係の更新PRをClaudeがレビュー AI_ONLYかつ指摘なしなら自動承認 セキュリティパッチの迅速な適用に貢献 Renovate PRの自動レビュー・承認 Renovateが作成した依存関係の更新PRは、専用ワークフロー（ ai-renovate-review.yml ）で自動処理されます。 自動承認の条件 patch / minorの安全な更新のみ 破壊的変更なし Blocker / Major指摘が0件 AI開発の効果測定（週次レポート） ai-metrics-report.yml により、AI駆動開発の効果を週次で自動計測し、GitHub Issueとして報告します。 計測される KPI 指標 目標 説明 AI_ONLYレビュー通過率 60％以上 AIのみで承認可能と判定されたPRの割合 自動承認率 - 実際に自動承認されたPRの割合 Devinの修正成功率 70％以上 Devinが修正を試みたPRのうち、マージに至った割合 イテレーション上限到達率 10％以下 修正ループが上限（3回）に達したPRの割合 平均イテレーション回数 1.5回以下 PRあたりの平均の修正回数 CI失敗率 20％以下 CI失敗が発生したPRの割合 レポート例 ## AI 開発効果測定 週次レポート **集計期間**: 2025-12-15 ~ 2025-12-22 **対象 PR 数**: 25 件 ### 📊 主要指標（KPI） | 指標 | 実績 | 目標 | 状態 | |------|------|------|------| | AI _ ONLY レビュー通過率 | 72.0% | 60% 以上 | ✅ | | 自動承認率 | 68.0% | - | - | | Devin 自動修正成功率 | 85.7% | 70% 以上 | ✅ | | イテレーション上限到達率 | 4.0% | 10% 以下 | ✅ | | 平均イテレーション回数 | 1.2 回 | 1.5 回以下 | ✅ | | CI 失敗率 | 16.0% | 20% 以下 | ✅ | 🎉 すべての主要指標が目標を達成しています！ このレポートは毎週月曜10:00 JSTに自動生成され、 ai-metrics ラベル付きのIssueとして作成されます。 AIコンテキストの自動育成 devin-context-refresh.yml により、PRコメントからのフィードバックを元にAIコンテキストドキュメントを週次で自動更新します。 動作フロー 更新対象ファイル カテゴリ ファイル ルート AGENTS.md docs/ai-context/ coding-standards.md , context.md , data-model.md , design-template.md , glossary.md , implementation-patterns.md , metrics.md , pr_review_classification.md , pr_review_comment_rules.md , role.md , task-assignment.md docs/guidelines/ architecture.md , environment-variables.md , error-handling.md , naming-conventions.md , validation.md docs/review-perspectives/ api.md , business.md , dependency.md , general.md , perf.md , quality.md , security.md , workflow.md ドキュメントの階層構造 AIエージェントがコンテキストを読み込む際、次の階層構造で参照が行われます。 CLAUDE.md：Claude Codeが最初に読み込むファイル。 @AGENTS.md でメインガイドを参照 AGENTS.md：AIエージェント向けメインガイド。最重要ルール（3-5個）と各ドキュメントへのパス参照を記載（300行未満を推奨） docs/：詳細情報は各サブディレクトリに委譲し、AGENTS.mdからパス参照のみ記載 この構造によってコンテキストの段階的読み込みが可能になり、トークン消費を抑えつつ必要な情報にアクセスできます。 各ディレクトリの役割 ディレクトリ 役割 使用タイミング CLAUDE.md Claude Codeのエントリーポイント。 @AGENTS.md でAGENTS.mdを参照 Claude Code起動時に自動読み込み AGENTS.md AIエージェント向けメインガイド。最重要ルール（3-5個）と各ドキュメントへの参照を記載 Devinがセッション開始時に読み込む docs/ai-context/ コーディング規約、実装パターン、用語集、データモデルなどのコンテキスト情報 Playbook内で参照先として指定。週次更新でPRコメントから学んだ知見を蓄積 docs/guidelines/ アーキテクチャ設計、エラーハンドリング、バリデーションなどの詳細な技術ガイドライン Playbook内で参照先として指定。週次更新で継続的に改善 docs/review-perspectives/ perspective:* ラベルに対応したレビュー観点ドキュメント Claude ReviewがPRのPerspectiveに応じて動的に読み込み（ 詳細 ） PRレビューで蓄積されたナレッジが自動的にドキュメントに反映されるため、Claudeのレビュー品質も継続的に向上していきます。 残っている課題 AIでも対応が難しいドメイン固有の判断があり、最終的に人間の合意が必要になるケースが残る ワークフローが複雑になり、運用ルールの理解・周知コストが発生している AIによる正しい指摘でも、チームの合意形成に時間を要する場合がある 運用上の注意点 スキップラベルの活用 特定のPRでAIレビューをスキップしたい場合は、次のラベルを使用します。 skip-ai-review : AIレビューを完全にスキップ renovate : Renovate PR（専用ワークフローで処理） 人間のレビューが必要なケース 次の変更は NEEDS_HUMAN と判定され、必ず人間のレビューが必要です。 セキュリティ関連の変更 ドキュメント・READMEの更新 設定ファイルの変更 スタイル・デザインの変更 ワークフロー別ラベル操作 ワークフロー 付与するラベル 削除するラベル ai-task-dispatcher.yml -（条件判定のみ、ラベル操作なし） - ai-task-implementation.yml in-progress in-progress （失敗時/キャンセル時） ai-review-orchestrator.yml ci-failed , ai-iteration-{N} , ai-auto-approved , needs-human-review ci-failed , ai-auto-approved , needs-human-review , perspective:* , ai-iteration-{N} pr-perspective-router.yml perspective:* perspective:* （再分類時） ai-renovate-review.yml perspective:dependency , renovate - ai-metrics-report.yml ai-metrics , automated （Issueに付与） - トラブルシューティング 問題 対処法 Devinセッションが開始しない DEVIN_API_KEY の設定を確認 Claudeレビューが実行されない AWS IAMロールの権限を確認 イテレーション上限に達した 手動で修正し、 ai-iteration-* ラベルを削除 CIタイムアウト CIの実行時間を確認、 CI_WAIT_MINUTES の調整を検討 まとめ この記事では、Claude（レビュー・判断）× Devin（実装・修正）の役割分担によるAI駆動開発ワークフローについて解説しました。 実現した効果 指標 Before After PRレビュー待ち時間 平均4時間 即時（Claudeが自動レビュー） レビュー指摘の修正 手動対応 Devinが自動修正 CIエラー修正 手動対応 Devinが自動修正（最大3回リトライ） Issue実装開始 平均1日 Slackから即時着手 Renovate PR 手動確認・マージ Claudeが依存関係レビューし、AI_ONLYかつ指摘なしなら自動承認 効果測定 なし 週次レポートでKPIを自動計測 ナレッジ育成 なし PRコメントからドキュメントを週次で自動更新 重要なポイント 役割分担：Claudeはレビュー（判断）、Devinは実装（作業）という明確な役割分担 人間との協調：AIはあくまでサポートであり、最終判断は人間が行う設計 段階的な自動化：すべてを自動化するのではなく、信頼性の高い部分から自動化 透明性：すべての判断理由がPRコメントとして記録される セーフティネット：イテレーション上限、キャンセル時のクリーンアップ、HEAD SHA検証 今後の展望 レビュー観点の自動学習 MCP連携強化 Confluenceドキュメント読み込み Figma MCPからデザイン取得 → 実装まで一気通貫 Jiraチケット起点の連携追加（Slackと同様のフローで起動） 人間レビューコメント時の対応方針の定義（優先度・担当・再レビュー） CodeRabbitとの併用検討 Slack通知の拡充（開始/完了/要人間対応などを分かりやすく通知） 最後に ZOZOでは、一緒にサービスを作り上げてくれる方を募集中です。ご興味のある方は、以下のリンクからぜひご応募ください。 corp.zozo.com 参考リンク anthropics/claude-code-action - Claude CodeのGitHub Action Devin API Documentation - Devin APIリファレンス

.entry .entry-content .table-of-contents > li > ul { display: none; } はじめに こんにちは。Developer Engagementブロック（略称DevEngブロック）の @wiroha です。ZOZO TECH BLOGの運営や、開発者向けイベントの企画・運営などを担当しています。 TECH BLOGの運営において、レビューには一定の工数がかかるため、効率化を進めています。その一環として、Claude CodeのAgent Skills（以下、スキル）を用いたレビュー支援の仕組みを整備しました。Claude Code上で記事のレビューを依頼すると、定義したルールに基づくレビュー結果を得られます。 以下は、スキルによるレビュー結果の抜粋です。 本記事では、このスキルを用いたTECH BLOGレビューの取り組みについて紹介します。 目次 はじめに 目次 背景・課題 解決の方針 スキルの設計 SKILL.md rules.md スキルの使用方法 実行例 導入効果 運用上の注意点 今後の展望 まとめ 付録：rules.md全文 背景・課題 ZOZO TECH BLOGは執筆したチーム内で技術的な正確性をレビューした後、DevEngブロックで文章表現・社内ルール準拠などをレビューして公開しています。DevEngブロックでは、現在2名体制で年間約100本の記事をレビューしており、次の課題があります。 担当者が少なく属人化しやすい 時間がかかってしまう 指摘が多いと漏れが発生しやすく、修正と再レビューの往復で進行が詰まりやすい 記事はGitHub上で管理しており、文章を校正する textlint のGitHub Actionsを動かしているため、ある程度のチェックは自動化されています。 1 ただ、それだけでは網羅できない観点が多くあるため、AIを活用してレビューの自動化をさらに推進することにしました。 解決の方針 AIを活用したレビューには複数の選択肢がある中で、Claude Codeのスキルを用いることにしました。Claude Codeはブラウザやエディタを介さず、ターミナル（CLI）で動作し、手元のファイルや外部サービスの情報を扱いながら作業を支援できるAIツールです。スキルは特定のタスクを実行するためのカスタムモジュールで、ドメイン知識やルールに基づいた処理を一貫した手順でAIに実行させられます。スキルの詳細はClaude Codeの公式ドキュメントをご覧ください。 code.claude.com 今回の場合、 claude コマンドでClaude Codeを起動し、「記事をレビューしてください」のように指示するだけで、スキルが呼び出されてレビューを実行できます。 AIレビューの手段として、ChatGPTのGPTsやGeminiのGemなど対話型AIのカスタマイズ、GitHub Actionsによる自動チェックも検討しました。最終的にスキルを採用した理由は次のとおりです。 ブラウザで使用するAIツールと異なり、記事本文をコピーしてAIにペーストする手間が省ける 同じ仕組みをDevEngブロック以外も使用でき、執筆者によるセルフレビューとしても使える 社内にはClaude Codeの利用者が多く、操作に慣れている レビュールールをGitHub上で管理し、誰でもPRを出して改善提案する運用にできる Claude Code GitHub Actions や Devin でPR上に自動コメントするよりは、任意利用から始めて少しずつAIの精度を高めたい 何度も実行しやすく、レビュールールを継続的に改善しやすい仕組みが重要だと考えました。 スキルの設計 Claude Codeの公式ドキュメント「 Claude をスキルで拡張する 」を参考に、TECH BLOGレビュー用のスキルを設計しました。 執筆時点でのスキルの内容を掲載します。スキル定義ファイルであるSKILL.mdと、TECH BLOGレビューのルールをまとめたrules.mdの2つのファイルで構成されています。 SKILL.md --- name: techblog-review description: "ZOZO TECH BLOGの記事をレビューする。「記事をレビュー」「テックブログをチェック」「entry.mdを確認」などのリクエストで起動" allowed-tools: Read, WebFetch --- ## テックブログ記事レビュー `entry.md` をZOZO TECH BLOGのルールに基づいてレビューします。 ### 手順 1. `entry.md` を読む 2. `rules.md` のルールに基づいてレビューする 3. 記事内のリンクをWebFetchで確認し、リンク切れがないかチェックする 4. 問題がある場合のみ、以下のルールで出力する（「問題なし」「確認のみ」といった項目は記載しない） ### 出力ルール **L{行番号}** - {観点}：{修正内容の要約} ```diff - {修正前の文} + {修正後の文} ``` ### 出力例 **L73** - 文法：「〜なこと」→「〜こと」 ```diff - ドキュメントが古いなことが原因で + ドキュメントが古いことが原因で ``` **L89** - 冗長表現：「〜というのは」→「〜のは」 ```diff - 自動化できるというのは大きな利点です。 + 自動化できるのは大きな利点です。 ``` descriptionには、スキルを起動する際のキーワードを記載しています。allowed-toolsには、スキルが使用できるツールを指定しています。Readは、rules.mdや記事原稿であるentry.mdを読むために必要です。記事内のリンク切れをチェックするために、WebFetchも許可しています。 rules.md 肝となるレビュールールは、DevEngブロックがこれまでに行ってきたレビューやSuggestコメントをもとにしています。Claude Codeに過去3年間のレビューコメントをGitHub CLI 2 で収集させ、ルール案を作成させました。PR上のレビュー履歴を資産として活用し、案は人手で精査してブラッシュアップしました。 以下では、rules.mdの一部を紹介します。全文は長くなるため、付録として記事の末尾に掲載します。 # ZOZO TECH BLOG レビュールール ## 1. 文体・表現 ### 1.1 文体の統一 - **である調とですます調を混在させない** - 基本的にですます調を使用する ### 1.2 文は短くする - **一文が長すぎると読みにくい** - 複数の情報を含む文は分割する - 目安：一文100文字以内 ### 1.3 口語表現の回避 - 口語表現は文語表現に置き換える | 口語 | 文語 | |------|------| | 〜なんですが | 〜ですが | | 無かったです | ありませんでした | | ですので | そのため / したがって | | ないですが | ありませんが | | 食わせる | 与える / 読み込ませる | ### 1.4 曖昧表現の回避 - 「〜と思います」より「〜です」を使う - 「〜ような」で曖昧にせず断定する - 断定できる場合は断定する ``` ❌ 複数の機能を一度にデプロイするようなリリースサイクルを採用していました。 ✅ 複数の機能を一度にデプロイするリリースサイクルを採用していました。 ``` これらの観点の一部は以前Zennの記事「 技術をわかりやすく伝えるテクニカルライティングのtips 」などにまとめて共有していましたが、そこに含まれない多くの観点を整理できました。なお、rules.mdに含まれる例文は、生成されたルール案をもとに手動で改変し、特定の記事が推測されないよう配慮しています。 スキルの使用方法 スキルはブログ執筆用リポジトリのルートに配置しているため、プロジェクトスキルとして自動的に有効になります。 Claude Code上で「今書いている記事をレビューしてください」などと指示すれば、スキルが起動してレビューを実行します。ローカルにある自分の記事をセルフレビューする場合の例は次のとおりです。 Use skill "techblog-review"? と聞かれるので「Yes」と答えると結果が返ってきます。 DevEngブロックのメンバーは、自分が書いていない記事もレビューします。ローカルにない記事もClaude Code上で「 <URL> の記事をレビューしてください」のように指示すれば、GitHub CLIを使って自動的に記事を取得し、レビューしてくれます。 手動でチェックアウトしてきたり、コピー＆ペーストしたりする必要がなく、非常に便利です。 実行例 本記事を執筆しながら、実際にスキルを使ってレビューした際の結果を例として紹介します。 1. SKILL.mdでの指定どおり、リンク切れをチェックして有効である旨を表示しています。 2. ルールに書いてある、冗長表現を見つけて指摘しています。 3. ルールに書いていない観点でもチェックしてくれます。行頭に不要なスペースが入っている例です。 4. リンクを埋め込み形式で表示するための embed:cite が誤って入っているのも見つけています。 5. ルールにある「正式名称・表記」の観点で、サービス名の誤りを指摘しています。 6. 広く知られているサービス名だけではなく、ファイル名の誤りも発見できるのは驚きでした。 7. TODOと書いていなくても、消し忘れか対応漏れかもしれないコメントを指摘しており、細やかです。 8. ルールにある「文の流れ」の観点はやや厳密にも感じますが、たしかに読点を入れた方が読みやすいため修正しました。 9. 次の例ではURLの誤りを指摘しており、それ自体は適切であるものの、修正案が英語版ドキュメントのURLになってしまっていました。手動で日本語の方に修正しましたが、こういった誤りもあるため、自動適用はせず人が確認する運用にしています。 以上のように、表記・記法・リンクといった観点を中心に、幅広く指摘できました。 導入効果 実行例で示したとおり、さまざまな観点でチェックできており、修正案を考える時間を短縮できるようになりました。rules.mdで定義した観点に基づき、過去30件のPRのレビューコメントをAIで分類したところ、約75％をカバーできると推定されました。残り25％は「文章の圧縮・再構成」「表現の適切さ」「説明の追加・明確化」といった文脈依存の判断が必要なもので、ルールベースでの検出ができない点でした。 これまで暗黙知としてDevEngブロックメンバーの中で蓄積されていたチェック観点を、rules.mdとして明文化し、AIが担えるようになりました。その結果、レビュー観点が個人の経験やスキルに依存しにくくなり、再現性のあるチェックが行えるようになっています。 また、特定分野の技術を知っていないと見つけづらいタイポなど、自分では見落としていた点も検出でき、記事の品質向上に寄与しています。細部のチェックをAIに任せることで、全体の構成やわかりやすさといった観点に意識を向けやすくなり、読みやすい記事づくりにつながっています。 執筆者にはまだ展開したばかりで、セルフレビューで用いるのは必須とはしていません。ルールの精度を向上させ、執筆段階でセルフレビューとして使うケースが増えていけば、修正と再レビューの往復が減り、執筆者・レビュアー双方の負担軽減につながると考えています。 運用上の注意点 実行例の部分にも記述したとおり、現在の運用ではAIの指摘をそのまま採用せず、提案として扱っています。指摘に誤りが含まれる場合や、厳密すぎる場合があるためです。たとえばルールでは口語表現を回避するよう定めていますが、イベントレポート系の記事では口語の表現を残した方が感情を伝えやすい場合もあります。そのあたりのバランスは人が判断しています。 また、社外秘や推測可能な情報が混入していないかなども人が確認しています。 今後の展望 今後は、スキルの精度向上と機能拡張に継続して取り組みます。記事をレビューした結果をもとにフィードバックループを回し、改善を図ります。 執筆者からの意見次第では、Claude Code以外のAIツールへの対応も検討しています。rules.mdを整備したことで、同じ観点を他のツールにも転用しやすくなりました。Claude Codeを使用していない人でも利用できる導線を用意してもよいかもしれません。 また、本記事に反響があれば、スキルをオープンソース化し最新のルールを社外の方も利用できるようにすることも検討したいと考えています。各社で技術ブログの運用方法は異なるため、本取り組みを通じて、より良いレビューや運用方法について意見交換ができればと思います。 まとめ 本記事では、Claude CodeのAgent SkillsとしてTECH BLOGのレビュー観点を集約し、効率化した取り組みを紹介しました。AIの発展は目覚ましく、優れたツールが次々と登場しています。DevEngブロックは新しい技術を積極的に取り入れ、より良い執筆体験を提供できるよう努めていきます。今回の記事が生成AIをレビュー支援に取り入れる際の設計・運用のヒントになれば幸いです。 ZOZOでは、一緒にサービスを作り上げてくれる方を募集中です。技術記事の執筆が好きな方も大歓迎です。ご興味のある方は、以下のリンクからぜひご応募ください。 corp.zozo.com 付録：rules.md全文 # ZOZO TECH BLOG レビュールール ## 1. 文体・表現 ### 1.1 文体の統一 - **である調とですます調を混在させない** - 基本的にですます調を使用する ### 1.2 文は短くする - **一文が長すぎると読みにくい** - 複数の情報を含む文は分割する - 目安：一文100文字以内 ### 1.3 口語表現の回避 - 口語表現は文語表現に置き換える | 口語 | 文語 | |------|------| | 〜なんですが | 〜ですが | | 無かったです | ありませんでした | | ですので | そのため / したがって | | ないですが | ありませんが | | 食わせる | 与える / 読み込ませる | ### 1.4 曖昧表現の回避 - 「〜と思います」より「〜です」を使う - 「〜ような」で曖昧にせず断定する - 断定できる場合は断定する ``` ❌ 複数の機能を一度にデプロイするようなリリースサイクルを採用していました。 ✅ 複数の機能を一度にデプロイするリリースサイクルを採用していました。 ``` ### 1.5 体言止めの回避 - **体言止めは曖昧になりやすいため、技術記事では避ける** - 文として言い切る形にする - **ただし、箇条書きの場合は体言止めでも許容** ``` ❌ 先月、ついに新機能をリリース。 ✅ 先月、ついに新機能をリリースしました。 ``` ### 1.6 「〜たり」の用法 - 並列の「〜たり」は**2回以上繰り返して使う** ``` ❌ コードを書いたりレビューができます ✅ コードを書いたりレビューをしたりできます ``` ### 1.7 「〜になります」「〜となります」の回避 - 変化しない場合は「です」を使う ``` ❌ 本ツールはログ収集の定番ライブラリになります。 ✅ 本ツールはログ収集の定番ライブラリです。 ``` ### 1.8 丁寧すぎる表現の回避 - 物に対する過剰な丁寧表現は避ける ``` ❌ 環境変数を設定ファイルに追記してあげる必要があります。 ✅ 環境変数を設定ファイルに追記する必要があります。 ``` ### 1.9 敬称 - 社外の方（技術顧問、登壇者等）には「さん付け」を使う - 自社社員には敬称は不要とする ### 1.10 簡潔にできる表現（任意） 簡潔にしたい場合は、以下のように表現を変える - 「なぜ〜したか」→「〜した理由」 - 「どのように〜するか」→「〜する方法」 - 「どれくらい閲覧されたか」→「閲覧数」 --- ## 2. 受動態と能動態 ### 2.1 能動態を優先する - **受動態が多いと読みづらくなる** - 主語を明確にして能動態で書く ``` ❌ 複数の設定ファイルはバッチ処理から順次実行されることで、対象システムの状態を更新していきます。 ✅ バッチ処理が複数の設定ファイルを順次実行し、対象システムの状態を更新します。 ``` ### 2.2 受動態と能動態の混在を避ける ``` ❌ そのAPIに対してタイムアウトを設定されており ✅ そのAPIにはタイムアウトが設定されており ``` --- ## 3. 主語と述語 ### 3.1 主語を省略しない - 主語がないと何の話かわからない ``` ❌ この処理の流れの特徴として、決済完了のタイミングで管理画面からメールをユーザーへ同期的に送信します。 ✅ この処理の流れの特徴として、システムは決済完了のタイミングで管理画面の機能を介してメールをユーザーへ同期的に送信します。 ``` ### 3.2 主語と述語のねじれを避ける - 主語と述語が対応しているか確認する ``` ❌ 特に気になった変更点は、新しいログ出力機能が追加されました。 ✅ 特に気になった変更点は、新しいログ出力機能が追加されたことです。 ❌ 今回の会場は、東京国際フォーラムで開催されました。 ✅ 今回の会場は、東京国際フォーラムです。 ✅ 今回のイベントは、東京国際フォーラムで開催されました。 ❌ 結論はコストと移行の容易さからマネージドサービスを選定しました。 ✅ 結論として、コストと移行の容易さからマネージドサービスを選定しました。 ``` ### 3.3 「〜とは」の後に意味を書く - 「〇〇とは」と書いたら、その後に定義・意味を書く ``` ❌ マイクロサービスアーキテクチャとは、システムを独立した小さなサービス単位に分割し、開発スピードと拡張性を大幅に向上させることができます。 ✅ マイクロサービスアーキテクチャとは、システムを独立した小さなサービス単位に分割し、開発スピードと拡張性を大幅に向上させる設計手法のことです。 ``` --- ## 4. 助詞の使い方 ### 4.1 助詞の誤用 | 助詞 | 悪い例 | 良い例 | |------|--------|--------| | を | サーバーを起動を開始 | サーバーの起動を開始 | | を | パラメータを設定をしました | パラメータを設定しました | | が | テスト実行にかかる時間が、全体時間を占める割合が増えた | テスト実行にかかる時間の、全体時間に占める割合が増えた | ### 4.2 助詞を省略しない ``` ❌ 空レスポンス ✅ 空のレスポンス ❌ パフォーマンス影響が出た ✅ パフォーマンスに影響が出た ❌ この項目は必須でありません ✅ この項目は必須ではありません ``` ### 4.3 助詞と動詞の対応 ``` ❌ 設定値を環境間に複製 ✅ 設定値を環境間で複製 ❌ 2018年より会社を設立しました ✅ 2018年に会社を設立しました （「より」は継続の開始を示すため、一時点の出来事には「に」を使う） ❌ 会場内にノベルティが配布されました ✅ 会場内でノベルティが配布されました ❌ このツールには標準で自動リトライ機能を提供しています ✅ このツールは標準で自動リトライ機能を提供しています ``` ### 4.4 冗長な表現を避ける | 冗長 | 簡潔 | |------|------| | 〜について | 〜を | | 〜に対して | 〜に | | 〜に関して | 〜の / 〜を | | 記載をします | 記載します | | 〜というのは | 〜のは | | 〜ということで | 〜ため / 〜ので | ``` ❌ 運用コストを削減できるというのは大きなメリットでした。 ✅ 運用コストを削減できるのは大きなメリットでした。 ``` ### 4.5 逆接でない「〜が」を避ける - 逆接でない「〜が」を接続に使うことを避ける - **主格の「が」は問題ない** - 単なる文の接続に「〜が」を使うのは避ける ``` ❌ 本機能は外部APIを利用してデータを取得しますが、取得したデータはデータベースへ保存され、ユーザー画面に表示されます。 ✅ 本機能は外部APIを利用してデータを取得します。取得したデータはデータベースへ保存され、ユーザー画面に表示されます。 ``` --- ## 5. 漢字とひらがなの使い分け ### 5.1 ひらがなにする語 - 公用文作成の要領や記者ハンドブックでは、実質的な意味を持たない言葉をひらがなで書くよう定めており、概ねそれに則る。 1. 常用外漢字 2. 形式名詞 3. 接続詞 4. 補助動詞 5. 一部の動詞 6. 副助詞 7. 副詞 など 具体例 | 漢字 | ひらがな | 分類 | 備考 | |------|----------|------|------| | 殆ど | ほとんど | 常用外漢字・副詞 | | | 為 | ため | 形式名詞 | 「〜のため」 | | 事 | こと | 形式名詞 | 「〜すること」 | | 所 | ところ | 形式名詞 | 「改善したいところ」 | | 尚 | なお | 接続詞 | | | 但し | ただし | 接続詞 | | | 又 | また | 接続詞 | | | 下さい | ください | 補助動詞 | 「ご確認ください」 | | 頂く | いただく | 補助動詞 | 「教えていただく」 | | 居る | いる | 補助動詞 | 「動いている」※補助動詞の場合 | | 無い | ない | 補助動詞 | 「問題ない」※補助形容詞の場合 | | 有る | ある | 補助動詞 | 「設定してある」※補助動詞の場合 | | 出来る | できる | 補助動詞・動詞 | | | 迄 | まで | 副助詞 | | | 位 | くらい/ほど | 副助詞 | | | 是非 | ぜひ | 副詞 | | | 丁度 | ちょうど | 副詞 | | | 更に | さらに | 副詞 | | | 予め | あらかじめ | 副詞 | | | 様々 | さまざま | 慣習 | 公用文では漢字表記 | ### 5.2 送り仮名の確認 ``` ❌ 楽しく話ながら作業した ✅ 楽しく話しながら作業した ``` --- ## 6. 語順・修飾 ### 6.1 修飾語は被修飾語の近くに置く ``` ❌ 細かいアーキテクチャの説明は省略します ✅ アーキテクチャの細かい説明は省略します ``` ### 6.2 語順を整理する ``` ❌ 過去1年間のコミット数を開発状況を可視化するダッシュボードで確認してみたところ ✅ 開発状況を可視化するダッシュボードで過去1年間のコミット数を確認してみたところ ``` ### 6.3 同じ単語・名詞の繰り返しを避ける - ただし、並列構造の場合は同じ単語が続いても問題ない ``` ❌ フローが複雑化してリードタイム低下とならないよう、フローの再設計を行いました。 ✅ 複雑化によるリードタイム低下を避けるため、フローの再設計を行いました。 # 並列構造の例（問題なし） ✅ 2024年には初期段階としてフェーズ1をリリースし、翌年の2025年には計画どおりフェーズ2をリリースしました。 ``` --- ## 7. 見出し・構成 ### 7.1 タイトル - 「〜の話」で終わるタイトルは避ける - 主題と副題をダッシュ（──）で繋ぐ形式を推奨 ### 7.2 見出しの統一 - 見出しの文体・形式を統一する（体言止め or 文） - 見出しがバラバラだと読みにくい ### 7.3 前提を書く - 読者が知らない前提（社内ルールなど）は明記する ### 7.4 結論から書く - 前置きが長いと読者が離脱する - 結論→理由→詳細の順で書く ### 7.5 「後述します」の多用を避ける - 「後述」を多用すると読者が混乱する - 可能な限りその場で説明する ### 7.6 文の流れを意識する - 唐突に話が変わらないようにする - 前後の文脈をつなげる ``` ❌ 現在、チームのチャットツールは有料プランで運用しています。必要な情報を後から見返せる仕組みは、業務上欠かせないと考えています。しかし無料プランへ移行すると、過去ログの検索期間に制限がかかります。 ✅ 現在、チームのチャットツールは有料プランで運用しています。無料プランへ移行すると、過去ログの検索に制限がかかります。業務上、情報を後から見返せる仕組みは不可欠と考えています。 ``` ### 7.7 複雑なことは図示する - 文章だけで説明が難しい場合は図を追加する --- ## 8. 記号・フォーマット ### 8.1 全角スラッシュは使わない - 「／」（全角スラッシュ）は使わない - 「/」（半角スラッシュ）または「・」を使う ### 8.2 英語の頭文字をとった略語は大文字 - API（Application Programming Interface）など、英語の頭文字をとった略語は大文字で表記する - class名やファイル名などで小文字表記の場合は例外とする ### 8.3 引用記法 - 引用記法（`>`）は**実際の引用のときのみ**使用する ### 8.4 CustomPathはハイフンつなぎ - アンダースコアは使わない ``` ❌ CustomPath: my_article_path ✅ CustomPath: my-article-path ``` ### 8.5 ダッシュの表記 - タイトルの主題と副題を繋ぐ際は**─を2つ + 前後に半角スペース**を使用 ``` ❌ システム移行の課題にどう立ち向かうか - 私たちが実践した解決策 ✅ システム移行の課題にどう立ち向かうか ── 私たちが実践した解決策 ``` --- ## 9. 正式名称・表記 ### 9.1 サービス・製品名は正式名称を使用 | 誤 | 正 | 参考URL | |----|----|----| | Golang | Go | https://go.dev/ | | Go言語 | Go | https://go.dev/ | | Spring boot | Spring Boot | https://spring.io/projects/spring-boot | | Alloy DB | AlloyDB | https://cloud.google.com/alloydb | | Firebase app check | Firebase App Check | https://firebase.google.com/docs/app-check | | Secrets manager | Secrets Manager | https://aws.amazon.com/secrets-manager/ | | slack bot | Slackbot | https://slack.com/help/articles/202026038 | | Kintone | kintone | https://kintone.cybozu.co.jp/ （小文字始まり） | | docker | Docker | https://www.docker.com/ （大文字始まり） | | JS Nation | JSNation | https://jsnation.com/ （スペースなし） | | iosDC | iOSDC Japan | https://iosdc.jp/ | | ArgoCD | Argo CD | https://argo-cd.readthedocs.io/ （スペースあり） | ### 9.2 社名・サービス名の正式表記 - 社名やサービス名は公式サイトを確認し、正式名称を使用する - スペースの有無、大文字小文字を正確に記載する - ルールに記載されていない名称も都度検索して確認すること **ZOZOに関する表記** - 「ZOZO」はZOZOTOWNの略称ではない - 「ZOZO Yahoo!店」→「ZOZOTOWN Yahoo!店」 --- ## 10. はてなブログ固有のルール ### 10.1 太字記法 - はてなブログでは `**太字**` の前後に半角スペースは入れない ### 10.2 埋め込み記法 - URLは埋め込み形式にすると見栄えが良い - `[https://example.com/:embed:cite]` ### 10.3 キャプション記法 - 画像にはfigureタグでキャプションを付けられる ```html <figure class="figure-image figure-image-fotolife" title="タイトル"> [f:id:vasilyjp:20230101120000] <figcaption>キャプション</figcaption> </figure> ``` ### 10.4 Markdownの改行 - パラグラフをわけるときは空行を入れる - 同じパラグラフ内で改行する必要がある場合は `<br>` か ` `（半角スペース2つ）による強制改行を使う。ただし、デバイス依存の表示崩れやSEO・アクセシビリティの低下などを招くため、必要な場合のみに留める。 ``` 1行目 2行目（別のパラグラフになる） ``` ### 10.5 箇条書きの前後には空行が必要 - 箇条書き（`-` や `1.`）の前後には空行を入れる - 空行がないとレイアウトが崩れる場合がある ``` ❌ 下記の項目を記載しています。 - 依頼の概要 - 依頼部門の課題 ✅ 下記の項目を記載しています。 - 依頼の概要 - 依頼部門の課題 ``` ### 10.6 続きを読む記法 - `<!-- more -->` ははてなブログで「続きを読む」の区切りとして使用される - このコメントは削除しない --- ## 11. リンク・参照 ### 11.1 リンク切れの確認 - リンクが有効か確認する（404になっていないか） ### 11.2 リンク先の確認 - リンク先が正しいか確認する - リンク先が不適切・不確かな情報でないか確認する ### 11.3 リンクテキストの書き方 - 「こちら」だけでなく、リンク先が分かるようにテキストを明示する ``` ❌ 詳しくは[こちら](https://example.com)をご覧ください。 ✅ 詳しくは[公式ドキュメント](https://example.com)をご覧ください。 ✅ 詳しくは「[独自のアプリケーションの作成](https://example.com)」を参考にしてください。 ``` ### 11.4 採用リンク - 記事末尾の採用リンクは有効か確認する --- ## 12. その他 ### 12.1 ファイル末尾 - ファイル末尾の改行は必須ではない ### 12.2 機密情報 - 機密情報が含まれていないか確認する - 例示で使う数字はダミーにし、その旨を明記する ### 12.3 将来の機能・予定 - 未確定の将来計画は公開可否を確認する ### 12.4 引用・著作権 - 他サイトの画像・スクリーンショットを使用する場合は引用の要件を満たす - 引用元を明記する - 参考: [文化庁「著作権を学ぶ（教材・講習会）」](https://www.bunka.go.jp/seisaku/chosakuken/seidokaisetsu/index.html) ### 12.5 画像の掲載許諾 - 人物写真は掲載許諾を確認する - 他社ロゴ・アイコンは使用許可を確認する ### 12.6 追記の書き方 - 記事公開後に追記する場合は日付を明記する ``` ❌ 追記：〜 ✅ （2023/5/16追記）〜（追記ここまで） ``` 既存の仕組みの詳細は TECH BLOG執筆支援のためのCI/CD導入事例 をご覧ください。 ↩ GitHub公式のコマンドラインツール https://docs.github.com/ja/github-cli/github-cli/about-github-cli ↩