■ 1. バックエンド開発Handbook
- Handbookの位置づけ:
- タイミーのバックエンド開発における設計、実装、運用のガイドラインをまとめたドキュメント集
- GitHub Pages でホスティングし、開発者が見やすい形で公開している
- GitHub Enterprise Cloud のアクセス制御機能により、リポジトリの読み取り権限を持つメンバーのみに公開範囲を制限している
- 執筆の背景:
- 事業の成長と変化に伴い、バックエンド開発に関わるエンジニアが増えてきた
- AIツールの進化も相まって、バックエンド以外を専門とするエンジニアが越境してコードを書く機会も増えている
- チーム内で暗黙的に共有されてきたノウハウや設計思想を形式知として残し、誰でもアクセスできる状態にする必要があった
- 戦略的プログラミングの重要性、概念モデリングの進め方、テーブル設計の注意点など、日々の開発で繰り返し必要になる判断基準を体系化している
- カバー範囲:
- 開発プロセスの全体を一気通貫でカバーしている
- はじめには戦略的プログラミングの心構え、秘匿情報の取り扱い、タイミーを取り巻く法律を扱う
- 設計は概念モデリング、ギャップ分析、テーブル設計、Web API設計、クラス設計、非同期処理設計、バッチ処理設計を扱う
- 実装、レビューは実装ガイドライン、コードレビュー、自動テスト設計、コードの整頓を扱う
- 運用、保守はログ設計、監視、障害対応を扱い、リリースはデプロイ、リリースを扱う
- 設計に重点を置く理由:
- バックエンド開発に慣れていない人がAIエージェントを使ったとしても、設計はカバーしにくい領域である
- 実装やレビューのプラクティスはある程度一般化されている
- タイミーのバックエンドとしてどう設計するかはチーム固有の知見が多く、形式知にする価値が高い
- 独自制約の記録:
- Sidekiq ジョブ実行中にデプロイが行われると Sidekiq プロセスに SIGTERM が送信される
- その25秒後には実行途中であってもジョブがキューに戻る制約がある
- 開発者はジョブをべき等にする、25秒を超えないよう処理対象を分割するなどの対策を行う必要がある
- このような暗黙的かつ独自の制約こそ Handbook として残すべきと考えていた
■ 2. Handbookをどう届けるか
- ドキュメント公開だけでは足りない:
- ドキュメントは自分から読みに行く必要があり、ひと手間かかる
- 存在を知っていても、忙しい開発中には思い出せないことがある
- AIエージェント経由という選択肢:
- 社内の多くのエンジニアがAIエージェントを日常的に使って開発している
- Claude CodeやCursorが開発フローに組み込まれているなら、AIエージェント経由でガイドラインを届けられる
- 開発者が意識しなくてもAIエージェントがガイドラインを参照しながら設計や実装を支援する状態を狙う
- 気づいたらガイドラインに沿った開発をしていたという状態を作れる
- 配布形式:
- Handbook公開と同時にAIエージェント向けスキルとしても提供することにした
- 現在は Claude Code Plugin と Cursor Agent Skills の2つの形式で配布している
■ 3. スキルの技術設計
- リポジトリ構成:
- Handbookのマークダウンドキュメントとスキル定義を同じリポジトリに同居させている
- backend 配下にドキュメント、.claude-plugin 配下にスキル定義、scripts 配下にCursor向け変換スクリプトを置く
- 原文とスキル定義が同居するため、ドキュメントの更新とスキルの更新を同じPRで行える
- ドキュメントとスキルが乖離するリスクを構造的に減らせる
- 2種類のスキル分類:
- スキルの役割に応じて Reference Skills と Workflow Skills という2種類の分類を独自に定義した
- これはClaude CodeやCursorの公式な分類ではなく、Handbookスキル群の設計方針として導入した概念
- Workflow Skill が高レベルに位置し、必要に応じて複数の Reference Skill を呼び出す
- Reference Skills:
- Handbookの各ページと1対1で対応する
- Web API設計、テーブル設計、クラス設計、コードレビューなどをスラッシュコマンドで呼び出せる
- context: fork を指定し、サブエージェントとして独立したセッションで実行する
- メインセッションのコンテキストウィンドウを消費せず、情報量の多いHandbook取得を委譲して要約のみを返す
- gh api -H "Accept: application/vnd.github.raw" でマークダウンの原文をそのまま取得する
- Handbookが更新されれば自動的に最新の内容が反映される
- Workflow Skills:
- 状況に応じて複数の Reference Skills を組み合わせるユースケース特化型のスキル
- context: current でメインセッション上で実行される
- 現在は理解、モデリング、計画、実装の4つを提供し、計画と実装は開発中
- モデリングのWorkflow Skillsはイントロダクション、ガイドライン取得、意図の深掘りと目標の合意、すり合わせの質問、モデリング実行の順で進む
- 開発者はスラッシュコマンドを1つ実行するだけで、ガイドライン参照からモデリング作業までを一気通貫で進められる
- ガイドラインの存在を知らなくても、Workflow Skillsが自動的に適用する
- 階層構造のメリット:
- 再利用性として、ギャップ分析などの同じReference Skillsが理解、モデリング、設計の各Workflowから呼ばれる
- 動的選択として、Workflow Skillsが入力や状況に応じて必要なReference Skillsだけを選択的に呼び出す
- コンテキスト効率として、ガイドライン取得処理をサブエージェントに委譲し、メインセッションには要約のみが返る
- 拡張性:
- Workflow Skillsは自作も可能で、チームの開発フローに合わせたワークフローを追加できる
- スキルが充実すれば、どのタスクでもHandbookの知見にガイドされる状態が作れる
- 新しくチームに加わった開発者でも、スキルを通じてチーム固有の設計方針をすぐにキャッチアップできる
■ 4. 人間の理解を置き去りにしない設計
- 前提となる問題意識:
- スキルの技術設計だけでは不十分であり、ここが一番気をつけたポイント
- AWSが提唱するAI-DLCは、AIの出力を妥当にジャッジできる人間の存在を前提としている
- 人間側の理解が伴わなければ成り立たない
- 現実にはAIの出力をなんとなく良さそうという理由でそのまま使い、理解が追いつかないケースが起きがち
- AIの進化で実装の詳細を把握しなくてよくなる部分はあるが、背景の考え方を理解しなければAIと適切にコミュニケーションを取れない
- スキル群は、いつでも質問できるメンターをAIで実現する試みである
- 工夫1: イントロダクションで理由を伝える:
- 各Workflow Skillsの冒頭にイントロダクションを設けている
- いきなり作業に入らず、なぜこのフェーズが重要か、このフェーズで何を学ぶかを説明する
- 理解フェーズでは、コード理解に概念、構造、実装の3段階があり概念レベルから順に深めるアプローチが有効だと説明する
- 工夫2: ガイドラインURLの提示:
- 全てのスキルで、参照したガイドラインのホスティングURLをユーザーに必ず提示する
- AIの要約だけで完結させず、元のドキュメントに戻れる導線を用意している
- 全体像を掴んだ上で、気になった箇所は原文で深掘りできる
- Handbookそのものの認知と活用が進む効果も期待している
- 工夫3: 抽象から具体へ段階的に:
- Workflow Skillsのフロー全体が、抽象度を段階的に下げていく設計になっている
- 理解、モデリング、計画、実装の4フェーズも、各フェーズ内も同様の構造を持つ
- 理解フェーズでは概念、構造、実装と段階的に深める
- 計画フェーズでは概念モデルの出来事やモノをAPIエンドポイントやテーブルへ変換する
- 一気に情報を出さず、フェーズごとにすり合わせの質問を挟み、開発者自身が考える余白を作る
- 企業合併の表現という思考実験では、汎用性の程度や合併の時間的フェーズを問う質問が返ってきた
- 合併に吸収と新設のパターンがあること自体を自分は知らなかった
- 設計ガイドラインを熟知したエキスパートとドメイン知識を持つエキスパートが結合した体験に末恐ろしさを感じた
- 工夫4: 各ステップに学習ポイントを明示:
- Workflow Skills内の各ステップに、なぜそうするのか、ここで何を学ぶかを明示している
- 出来事はAPIエンドポイント、モノはリソースとリクエストおよびレスポンス、ビジネスルールはバリデーションとエラーハンドリングに対応づける
- 出来事は動詞で考え、APIでは名詞であるリソースとして表現する
- 選択された名前をリソース名に反映する
- 手順だけでなく背景の考え方を伝え、AIが出す結果の理由を開発者自身が理解できる状態を目指す
■ 5. 使ってみての反応
- 自分自身の所感:
- これまでとは一線を画す体験だと感じている
- 従来のAIエージェントの出力は一気に大量の情報を出し、情報量に圧倒されて消化しきれないことがあった
- このワークフローは抽象度を段階的に下げながら教えるため理解しやすい
- 会話で賢いと感じる人が抽象から具体へ落としていくのが上手な点と同じ感覚がある
- これまでAIエージェントに開発のギアが上がる感覚はなかったが、このワークフローは明確にゲームチェンジャーだと感じている
- VPoEの反応:
- 実際に動かしながら紹介したところ、その場でEMチャンネルに @here 付きで共有してくれた
- AIエージェントが段階的にガイドラインを適用しながら開発者と対話する体験に手応えを感じてもらえた
- 他開発チームメンバーの反応:
- 社内への全体発信を終え、各チームへのハンズオンを順次進めている段階で既に手応えがある
- 普段の開発で使っているエンジニアから、ここ1、2年で一番刺さったプロダクトだというコメントをもらった
■ 6. AI時代の開発組織
- 取り組みの要点:
- ドキュメントを書くだけでなく、AIエージェントを介して開発フローへ自然に組み込む新しいアプローチを模索している
- AIへ任せきりにせず人間側の理解を促すことが、知の高速道路を敷くうえで最も大事なポイント
- 必要な2つの要素:
- 短期目線での開発の高速化だけでは不十分
- 全タスクがオンボーディングタスクになっていること
- メンターを基本的にAIが担い、いくらでも質問できて自走できる環境が整っていること
- 期待する効果:
- 2つが揃えば、誰でもどのチームに移っても素早く立ち上がれる
- 必要な場所に必要な人材を配置できる人員の流動性の高さに直結する
- Handbookとスキルの取り組みはその第一歩