こんにちは、タイミーでバックエンドのテックリードをしている新谷（@euglena1215）です。

今回は、社内向けに公開したバックエンド開発Handbookと、それをClaude CodeやCursorといったAIエージェント向けスキルとして届けることで、気づいたらHandbookを参照している状態を目指した取り組みについて紹介します。

バックエンド開発Handbookとは何か

バックエンド開発Handbookは、タイミーのバックエンド開発における設計・実装・運用のガイドラインをまとめたドキュメント集です。GitHub Pages でホスティングし、開発者が見やすい形で公開しています。

タイミーでは GitHub Enterprise Cloud を利用しているため、GitHub Pages のアクセス制御機能でリポジトリの読み取り権限を持つメンバーのみに公開範囲を制限できます。

なぜ書き始めたのか

事業の成長・変化に伴い、バックエンド開発に関わるエンジニアが増えてきました。AIツールの進化も相まって、バックエンド以外を専門とするエンジニアが越境してコードを書く機会も増えています。

こうした変化の中で、これまでチーム内で暗黙的に共有されてきたノウハウや設計思想を形式知として残し、誰でもアクセスできる状態にしておく必要がありました。

たとえば戦略的プログラミングの重要性、概念モデリングの進め方、テーブル設計の注意点など、日々の開発で繰り返し必要になる判断基準を体系化しています。

カバー範囲

Handbookは開発プロセスの全体を一気通貫でカバーしています。

フェーズ	トピック
はじめに	戦略的プログラミングの心構え、秘匿情報の取り扱い、タイミーを取り巻く法律
設計	概念モデリング、ギャップ分析、テーブル設計、Web API設計、クラス設計、非同期処理設計、バッチ処理設計
実装・レビュー	実装ガイドライン、コードレビュー、自動テスト設計、コードの整頓
運用・保守	ログ設計、監視、障害対応
リリース	デプロイ・リリース

設計に重点を置いているのは、バックエンド開発に慣れていない人がAIエージェントを使ったとしても、カバーしにくい領域だからです。実装やレビューのプラクティスはある程度一般化されていますが、「タイミーのバックエンドとしてどう設計するか」はチーム固有の知見が多く、形式知にする価値が高いと考えました。

たとえばタイミーでは、Sidekiq ジョブ実行中にデプロイが行われると、Sidekiq プロセスに SIGTERM が送信されます。その25秒後にたとえ実行途中であってもジョブをキューに戻す、という実装上の制約があります。開発者はこれを考慮してジョブの処理をべき等にしたり、25秒を超えないように処理対象を分割してジョブに切り出すなどの対策を行う必要があります。このような暗黙的かつ独自の制約は特に Handbook として残すべきだろうと考えていました。

Handbookをどう届けるか

Handbookを書いて公開するだけでも価値はありますが、ドキュメントは自分から読みに行く必要があり、ひと手間かかります。存在を知っていても、忙しい開発中には思い出せないこともあると思います。

いま、社内の多くのエンジニアがAIエージェントを日常的に使って開発しています。Claude CodeやCursorなどのツールが開発フローに組み込まれているのであれば、AIエージェント経由でガイドラインを届けるという選択肢があります。

開発者が意識しなくても、AIエージェントがガイドラインを参照しながら設計や実装を支援してくれる。そうすれば、「気づいたらガイドラインに沿った開発をしていた」という状態を作れます。

この考えから、Handbook公開と同時にAIエージェント向けスキルとしても提供することにしました。現在、Claude Code Plugin と Cursor Agent Skills の2つの形式で配布しています。

ここからは、AIエージェント向けスキルの技術的な仕組みと、人間側の学びを促す工夫の2つの観点で説明します。

スキルの技術設計

リポジトリ構成

1つの工夫として、Handbookのマークダウンドキュメントとスキル定義を同じリポジトリに同居させています。

handbook/
├── backend/                    # Handbookドキュメント（マークダウン）
│   ├── design/
│   │   ├── web_api_design.md
│   │   ├── table_design.md
│   │   └── ...
│   ├── implementation/
│   └── operation/
├── .claude-plugin/             # AIエージェント向けスキル定義
│   └── timee-backend-handbook/
│       ├── plugin.json
│       └── skills/
│           ├── ref-design-api/
│           ├── wf-code-reading/
│           └── ...
└── scripts/
    └── build-cursor-skills.sh  # Cursor向け変換スクリプト

ガイドラインの原文とスキル定義が同じリポジトリにあるため、ドキュメントの更新とスキルの更新を同じPRで行えます。ドキュメントとスキルが乖離するリスクを構造的に減らせます。

Reference SkillsとWorkflow Skills

Handbookの内容を、AIエージェントのスラッシュコマンドで呼び出せるSkillsとして提供しています。今回、スキルの役割に応じてReference SkillsとWorkflow Skillsという2種類の分類を独自に定義しました。これはClaude CodeやCursorの公式な分類ではなく、Handbookスキル群の設計方針として導入した概念です。

Workflow Skill（高レベル）
├── Reference Skill A を呼び出し
├── Reference Skill B を呼び出し
└── Reference Skill N を呼び出し（必要に応じて）

Reference Skills

Reference SkillsはHandbookの各ページと1対1で対応します。

/handbook-ref-design-api          # Web API設計
/handbook-ref-design-table        # テーブル設計
/handbook-ref-design-class        # クラス設計
/handbook-ref-impl-code-review    # コードレビュー
...

たとえばAPI設計のReference Skillsは以下のように定義されています。

---
name: handbook-ref-design-api
description: Web API設計のガイドラインを参照してエンドポイント設計をレビュー・提案
context: fork
agent: general-purpose
allowed-tools: Bash(gh *)
---

## Web API設計ガイドライン

!`gh api /repos/my-org/handbook/contents/backend/design/web_api_design.md -H "Accept: application/vnd.github.raw"`

## タスク

上記のガイドラインに従って、$ARGUMENTS のWeb API設計をレビュー・提案してください。

ポイントは context: fork です。サブエージェントとして独立したセッションで実行されるため、メインセッションのコンテキストウィンドウを消費しません。情報量の多いHandbookの取得をサブエージェントに委譲し、要約のみを返すことで効率的に運用できます。

また、gh api -H "Accept: application/vnd.github.raw" でマークダウンの原文をそのまま取得できます。Handbookが更新されれば自動的に最新の内容が反映されます。

Workflow Skills

Workflow Skillsは、状況に応じて複数のReference Skillsを組み合わせるユースケース特化型のスキルです。context: current でメインセッション上で実行されます。

現在はWorkflow Skillsを4つ提供しています。

スキル	フェーズ	内容
`/handbook-wf-code-reading`	理解	既存機能を体系的に理解する
`/handbook-wf-modeling`	モデリング	概念モデリングを実施する
`/handbook-wf-plan`	計画	開発中: 詳細設計を行いつつ、複数個の実装計画に落とし込む
`/handbook-wf-implement`	実装	開発中: 与えられた入力を元に実装する

たとえばモデリングフェーズのWorkflow Skillsを実行すると、以下のような流れで進みます。

イントロダクション: 概念モデリングの重要性とギャップ分析の考え方を説明
ガイドライン取得: 必要なReference Skills（概念モデリング、ギャップ分析など）を自動で選択・呼び出し
意図の深掘りと目標の合意: 何をモデリングしたいのか、スコープを確認
すり合わせの質問: ドメインの境界やビジネスルールについて質問を提示
メインセッションでモデリング実行: 回答を踏まえて一緒にモデリングを進める

開発者はスラッシュコマンドを1つ実行するだけで、必要なガイドラインの参照からモデリング作業までを一気通貫で進められます。ガイドラインの存在を知らなくても、Workflow Skillsが自動的に適用してくれます。

階層構造のメリット

Reference SkillsとWorkflow Skillsの2層構造には、以下のメリットがあります。

再利用性: 同じReference Skills（たとえばギャップ分析）が理解・モデリング・設計の各Workflowから呼ばれる
動的選択: Workflow Skillsがユーザーの入力や状況に応じて、必要なReference Skillsだけを選択的に呼び出す
コンテキスト効率: ガイドラインの取得処理はサブエージェントに委譲され、メインセッションには要約のみが返る

また、Workflow Skillsは自作も可能です。既存のWorkflow Skillsを参考にしながら、チームの開発フローに合わせたワークフローを追加していけます。こうしたスキルが充実すれば、どのタスクに取り組むときでもHandbookの知見にガイドされる状態が作れます。新しくチームに加わった開発者でも、スキルを通じてすぐにチーム固有の設計方針をキャッチアップできるはずです。

人間の理解を置き去りにしない設計

スキルの技術設計だけでは不十分です。ここが一番気をつけたポイントです。

AWSが提唱しているAI-DLC（AI Driven Development Life Cycle）は、AIの出力を妥当にジャッジできる人間の存在を前提としています。人間側の理解が伴わなければ成り立ちません。

しかし現実には、AIの出力を「なんか良さそうだから」とそのまま使ってしまい、人間側の理解が追いつかないケースも起きがちです。AIの進化によって実装の詳細を人間が把握しなくてよくなる部分はあるでしょう。ですが、背景にある考え方を理解していなければ、AIと適切にコミュニケーションを取ることはできません。

だからこそ、このスキル群では人間に考え方やインサイトをインプットする工夫を随所に入れています。いわば、いつでも質問できるメンターをAIで実現する試みです。

工夫点１：イントロダクションで「なぜ」を伝える

各Workflow Skillsの冒頭にイントロダクションを設けています。ここではいきなり作業に入るのではなく、「なぜこのフェーズが重要なのか」「このフェーズで何を学ぶのか」を説明します。

たとえば理解フェーズのイントロでは、コード理解には概念・構造・実装の3段階があり、概念レベルから順に深めるアプローチが有効であることを説明しています。

## 推奨アプローチ

概念レベルから順に理解を深めることを推奨します：

1. 概念レベル: まず全体像を掴む（どんな世界なのか）
2. 構造レベル: データとクラスの設計を理解（どう表現されているか）
3. 実装レベル: 具体的なロジックを理解（どう動くのか）

工夫点２：ガイドラインURLの提示

全てのスキルで、参照したガイドラインのホスティングしているURLを、ユーザーに必ず提示するようにしています。

重要: 参照したガイドライン（https://{my-org}.github.io/handbook/backend/design/web_api_design.html）
をユーザーに必ず提示してください。

AIの要約だけで完結させず、元のドキュメントに戻れる導線を用意しています。全体像を掴んだ上で、気になった箇所は原文で深掘りできます。Handbookそのものの認知と活用が進む効果も期待しています。

工夫点３：抽象から具体へ段階的に

Workflow Skillsのフロー全体が、抽象度を段階的に下げていく設計になっています。

ワークフローの4フェーズ（理解→モデリング→計画→実装）がそうですし、各フェーズ内でも同様です。理解フェーズでは概念→構造→実装と段階的に深め、計画フェーズでは概念モデルの出来事やモノをAPIエンドポイントやテーブルへ変換していきます。

一気に情報を出すのではなく、フェーズごとにすり合わせの質問を挟むことで、開発者自身が考える余白を作っています。

以下は、思考実験として「タイミーで企業合併を表現するなら？」というお題で、モデリングのWorkflow Skillsを試したときの様子です。

「将来の新設合併対応を見据えて、今回のモデルはどの程度汎用的にすべきですか？」「合併には時間的なフェーズがありますか？」という質問が飛んできました。そもそも合併に吸収・新設のパターンがあることを私は知りませんでした。Handbookの設計ガイドラインを熟知したエキスパートと、ドメイン知識を持ったエキスパートが悪魔合体するとこんな体験になるのか、と末恐ろしくなった瞬間です。

工夫点４：各ステップに学習ポイントを明示

Workflow Skills内の各ステップには「なぜそうするのか」「ここで何を学ぶか」を明示しています。

📚 学習ポイント:
- 出来事（申請する、承認する）→ APIエンドポイント
- モノ（勤務実績、勤務時間）→ リソースとリクエスト/レスポンス
- ビジネスルール → バリデーションとエラーハンドリング

💡 ガイドラインのポイント:
- 出来事は動詞で考え、APIでは名詞（リソース）として表現
- 選択された名前（例：「勤務実績」）をリソース名に反映

作業の手順だけでなく、その背景にある考え方を一緒に伝えることで、AIが出す結果の「なぜ」を開発者自身が理解できる状態を目指しています。

使ってみての感想

自分自身の所感

実際に使ってみて、これまでとは一線を画す体験だと感じています。

従来のAIエージェントの出力は、一気にたくさんの情報を出してくることが多く、情報量に圧倒されて消化しきれないことがありました。ですが、このワークフローでは抽象度を段階的に下げながら教えてくれるので理解がしやすいです。普段の会話で賢いなと感じる人は、抽象的なところから徐々に具体へ落としていくのが上手ですが、このワークフローにも同じ感覚があります。

AIエージェントは便利な開発アシストツールだと思いつつも、開発のギアが上がる感覚はこれまでありませんでした。ですが、このワークフローは明確にゲームチェンジャーだと感じています。

VPoEの反応

VPoEに実際に動かしながら紹介したところ、その場でEMチャンネルに @here 付きで共有してくれました。特に、AIエージェントが段階的にガイドラインを適用しながら開発者と対話する体験に手応えを感じてもらえたようです。

他開発チームメンバーの反応

現在、社内への全体発信を終えて各チームへのハンズオンを順次進めているところですが、すでに手応えを感じ始めています。

既に普段の開発で使ってくれているエンジニアからはこんなコメントをもらっています。ありがたい限りです。

handbookはここ1,2年で一番自分に刺さったプロダクトです

おわりに

この記事では、バックエンド開発Handbookと、それをAIエージェント向けスキルとして届ける取り組みについて紹介しました。

ドキュメントを書くだけでなく、AIエージェントを介して開発フローへ自然に組み込むことで、ガイドラインを届ける新しいアプローチを模索しています。AIへ任せきりにせず人間側の理解を促すことが、知の高速道路を敷くうえで最も大事なポイントだと考えています。

今回の取り組みを通じて、AI時代の開発組織に必要な要素が見えてきた気がしています。短期目線での開発の高速化だけでは不十分で、「全タスクがオンボーディングタスクになっていること」「メンターを基本的にAIが担い、いくらでも質問できて自走できる環境が整っていること」。この2つが揃えば、誰でもどのチームに移っても素早く立ち上がれるようになります。つまり、必要な場所に必要な人材を配置できる人員の流動性の高さに直結します。Handbookとスキルの取り組みは、その第一歩です。

今回作成した Agent Skills はカジュアル面談でもデモできるので、興味ある方はお気軽にお声がけください！実際に触ってみたい方は、ぜひタイミーに入社してください！

product-recruit.timee.co.jp

Timee Product Team Blog

タイミー開発者ブログ

バックエンド開発Handbookを届けるために ― AI時代の知の高速道路を敷く