Timee Product Team Blog

タイミー開発者ブログ

3日間のUnicorn Gymが1ヶ月で組織を変えた —— データで見るAI-DLC導入の波及効果

こんにちは。タイミーでPlatform Engineeringグループのマネージャーを務める橋本(@kaz-under-the-bridge)です。

2026年1月26日〜28日の3日間、AWS様と共同で AI-DLC Unicorn Gym(以下UG)を開催しました。私はタイミー側のカウンターパートとして、企画・準備から当日の運営、振り返りまでを担当しました。

AI-DLC(AI-Driven Development Life Cycle)は、要件定義からリリースまでの開発プロセス全体にAIを深く組み込むことで、従来のアジャイル開発を大幅に加速するアプローチです。Unicorn Gymは、AI-DLCを実際のプロダクト開発テーマで短期集中的に実践できる体験的な取り組みです。AWS様の支援のもと、国内でも多くの企業が参加・開催しています。

タイミーでは11チーム・約69名が参加し、各チームが実際にプロダクション搭載予定の機能をテーマにAI-DLCを実践しました。当日の実施内容、各チームの成果、参加者の声についてはAWS様の執筆レポートに詳しく書かれていますので、ぜひそちらもご覧ください。

株式会社タイミー様の AI-DLC Unicorn Gym 開催レポート: 全社横断で挑む開発生産性の変革

本記事では、UG当日の内容ではなく 「UGの後、組織に何が起きたのか」 を、実施から約1ヶ月時点のデータを交えてレポートします。

個の生産性改善から、組織のムーブメントへ

UG以前、タイミーにおけるAIツールの活用はエンジニアが個人個人で使いこなす 「個の生産性改善」 が主たるものでした。各自がCopilotやCursor、Claude Codeなどを独自に活用し、それぞれのやり方で生産性を高めていました。

それがUGを経て、チーム・組織単位でCoding Agentを使いこなす方向に大きくシフトしたと見ています。以下、データでその変化を追っていきます。

Claude Code利用者数の変化

タイミーのプロダクト開発組織では、以下のCoding Agentを利用しており、申請制で自由に使えるようにしています。

利用しているCodingAgent

私は上記ツール群の管理者でもあります。UG後に最初に気づいた変化は Claude Codeの利用申請が明らかに増えた ことでした。

CCシート数推移

UG前は週1〜2名ペースだったシート追加が、UG後は 週8名と約5倍に加速 しています。1ヶ月で85名から118名へ、1.4倍に拡大しました。

Skills/Plugin整備の加速 —— 組織的なAI活用への転換

利用者数の増加だけでなく、GitHubリポジトリ上のAI-DLC関連アクティビティ にも顕著な変化が見られました。

ここで言う「Skills」とは、Claude CodeのSkills機能を指します。指示・テンプレート・スクリプトをパッケージ化してリポジトリに配置すると、Claudeが会話内容に応じて自動で発見・ロードする仕組みです。たとえば「PRレビューの観点」や「テスト設計の手順」をSkillとして定義しておけば、チームの誰がClaude Codeを使っても同じ品質で作業できるようになります。

指標 UG前 UG後(1ヶ月時点) 変化
CLAUDE.md保有リポジトリ 3 37 +34
Skills保有リポジトリ 1 11 +10
Skills総数 3 78 +75

UG前、Skillsを持つリポジトリは たった1つで3 Skillsだけでした。それがUG後は 11リポジトリ・78 Skills に急拡大しています。

CLAUDE.md(Claude Codeのプロジェクト設定ファイル)を持つリポジトリも3から37へ。これは「AIにプロジェクトの文脈を伝える」取り組みが組織全体に広がりつつあると見ています。

つまり、個人がAIツールを使いこなすフェーズから、チームがSkillsを整備して組織的にAIを活用するフェーズ へ移行していると見ています。

エンジニア以外の職種への広がり

この組織的なAI活用の進展を補強するデータとして、利用者の職種構成の変化 があります。

プロダクト組織の人数と照らし合わせると、エンジニアのClaude Code利用率はUG前の約70%からUG後 約89% へ上昇し、ほぼ全員が使っている状態になっています。一方、エンジニア以外の方の利用率はUG前の7%からUG後 約27% へ。まだ道半ばではありますが、エンジニア以外の方もClaude Codeを使い始める段階に来ていると言えます。

UG前後でのCC普及率比較

Skillsの整備によってチーム単位でのAI活用基盤が整ったことで、PdMやデザイナーにとってもCoding Agentが使える環境が生まれつつあると見ています。

何が変わったのか —— 代表的な変化のパターン

Skillsの急増を支える具体的な動きを、いくつかのパターンに分類して紹介します。

既存リポジトリのAI-DLC駆動への変容

最も大きな変化を見せたのが、UG参加チームの既存プロダクトリポジトリです。UG前はCursorのコマンド設定がある程度だったリポジトリが、UG後には 23のSkillsと独自のAI-DLCフレームワーク を構築するまでに至りました。

コミットの中身を見ると、UG後は、Skillsの追加やAI-DLCフレームワークの構築、Inceptionの成果物(ユーザーストーリー、受け入れ基準、コンテキストマップ等)といった AI-DLCに関するコミットが大きな割合を占める ようになっています。これにより、個人がAIツールを使う段階から、チーム全体でAI-DLCのInception(要件定義)フェーズを実践し、プロダクト機能の設計にAIを組み込む段階へとシフトしたと見ています。

このチームの取り組みについては以下の記事もご覧ください。

失敗から学んだ仕様駆動開発――チームの暗黙知を形式知化した1ヶ月の実践と次の課題

ゼロからのAI-DLCワークスペース構築

UGをきっかけに、新たにリポジトリを立ち上げたチームも複数あります。UG初日に作成されたワークスペースの中には、backend・iOS・Androidなどのドメイン別Skills(7つ)や、inception・constructionといったAI-DLCのフェーズ別コマンド体系が整備され、今もSkillsやテンプレートの追加・改善を重ねているものもあります。

Knowledge-as-Code

特筆すべきは、ハンドブック(社内ナレッジ)をAI Skillsとしてコード化 する取り組みです。バックエンド開発のベストプラクティス、API設計指針、テスト設計、法的考慮事項の参照といった組織知を22のSkillsとして整備し、Claude Code Pluginとして提供しています。さらに、Cursor向けへの変換パイプラインも構築されており、複数のCodingAgentで活用できる仕組みになっています。

これは単なるツール活用を超えた、組織の暗黙知をAIが活用可能な形式知に変換する 取り組みと言えます。

こちらの取り組みについては以下の記事もご覧ください。

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

Claude Skill を Cursor の Agent Skill として使えるようにした話

UG中の学びの即時適用

既にClaude Codeを活用していたチームの中には、UG 3日目(1/28)に新しいSkillsを追加 した事例もあります。agentsやcommandsで安定運用していた状態から、UGでSkillsという新しいレイヤーを学び、その場で自チームのリポジトリに適用しているケースもありました。

UG非参加チームへの波及

興味深いのは、UGに参加していないチームにもAI-DLCの動きが広がっている ことです。UG非参加のチームが8つのSkills(ワークフロー自動化特化)を持つリポジトリを立ち上げるなど、UG参加チームの取り組みが周囲に波及しています。

これらの変化をどう見るか

数字を俯瞰すると、UGを境に起きた変化の本質は 「個のAI活用」から「組織のAI-DLC実践」へのシフト だと考えています。

  • 利用者の拡大: 週1.5名 → 週8名(5倍加速)、エンジニア以外の職種にも拡大
  • Skillsの整備: 1リポジトリ3 Skills → 11リポジトリ78 Skills(個人の効率化ではなく、チームの知識をAIに教える方向)
  • チームを超えた波及: UG非参加チームにも動きが広がっている

UGはあくまできっかけであり、3日間のイベントです。しかし、そのきっかけが 1ヶ月で組織全体の行動パターンを変えた ことは、データが示しているのではないかと思います。

おわりに

現時点では、ムーブメントはまだ初速の段階です。ただ、この動きは定着していくだろうと見ています。次にやるべきことは、AIを安全に使うためのセキュリティ面の整備と、より大きなうねりにしていくためのブロッカーを一つひとつ排除することだと考えています。

もちろん、本記事で取り上げたのはClaude Codeを中心とした変化に限っています。CursorやCopilotを活用して成果を出しているケースも多くあり、組織全体のAI活用はさらに広がりを見せています。

UG開催を検討されている方へ

最後に、主催者としてひとこと。UGの開催にあたって最初に立ちはだかる壁は、「参加者が乗り気になるかどうか」かもしれません。3日間という拘束時間の長さ、AI-DLCという新しい手法への不確実性——二の足を踏む気持ちは十分にわかります。

ただ、本記事でお伝えしたとおり、タイミーではUGの3日間をきっかけに1ヶ月で組織の行動パターンが変わりました。利用者の急増、Skillsの整備、エンジニア以外への波及。これらは3日間の投資に対して余りある効果だったと感じています。開催を迷っている方にとって、一つの事例として参考になれば幸いです。

最後まで読んでいただき、ありがとうございました。こうした取り組みに興味を持っていただけた方、一緒にチャレンジしてくれる方を募集しています!

タイミーの採用情報はこちら

Claude Skill を Cursor の Agent Skill として使えるようにした話

こんにちは!タイミーでバックエンドエンジニアとして働いている福井 (bary822) です。

皆さんは「Claude Code の Skills を社内の Cursor ユーザーも使えるようにしたい」と思ったことはないでしょうか?

Claude Code には Claude Plugin という仕組みがあり、社内で共有したい Skills を簡単に配布できます。しかし、Cursor には Claude Plugin に相当する機能がなく、さらに Claude Code の Skills は独自の構文をサポートしているため、そのままでは動作しません。

この記事では、Claude Plugin 形式で配布している Skills を Cursor でも利用できるようにした取り組みについてご紹介します。

背景

タイミーでは、社内の開発ガイドラインに沿った開発を行いやすくすることを目的に、Claude Code の Skills を整備し、Claude Plugin 経由で配布しています。

tech.timee.co.jp

Claude Code の Skills はエージェントに対してタスク実行時のコンテキストや手順を提供する機能です。この機能はもともと Claude Code 独自のものでしたが、現在では Agent Skills としてファイル名やディレクトリ構成、メタデータの種類などのオープンスタンダードが確立されつつあり、さまざまなAIプラットフォームで再利用できるようになっています。

Skills for organizations, partners, the ecosystem | Claude

Overview - Agent Skills

課題: Claude Plugin で配布している Skills を Cursor で使えない

Agent Skills の仕様自体は標準化が進んでいますが、配布の仕組みやサポートされる構文にはプラットフォーム間で差分があります。

配布の仕組みの差分

Claude Code には Plugin という仕組みがあり、Skills のインストール・アップデートを簡単に行えます。一方、Cursor には同等の配布機構がサポートされていません。

構文の差分

Claude Code の Skills には、Cursor でサポートされていない独自構文がいくつかあります。

  • !command 構文: SKILL.md 内で許可されたシェルコマンドを実行する構文。たとえば !gh api ... と書くことで GitHub API 経由でドキュメントを動的に取得できる。Cursor ではサポートされていない
  • $ARGUMENTS 変数: スキル実行時にユーザーが渡す引数を受け取るための変数。こちらもCursor ではサポートされていない

つまり、Claude Plugin で配布している Skills をそのまま Cursor に持ってきても、動的なコンテンツ取得ができず引数も渡せないため、まともに動作しない状態でした。

Cursor ユーザーにも同じ体験を提供するために、これらの構文を Cursor が理解できる形式に変換し、適切なディレクトリに配置する必要がありました。

解決策:変換スクリプトの作成

Claude Plugin 形式の Skills を Cursor 互換形式に変換するシェルスクリプト build-cursor-skills.sh を作成しました。

このスクリプトは以下の変換を行います。

  1. 動的コンテンツの埋め込み: !command 構文で動的に取得していたコンテンツを、ローカルのファイルから読み取ってテキストとして直接 SKILL.md に埋め込む
  2. 変数の変換: $ARGUMENTS を「ユーザーの指示に従って」という固定テキストに置換する
  3. 補助ファイルのコピー: Skills が参照する補助ファイル(intro.md, workflow.md, troubleshooting.md など)もコピーする

変換後の Skills を構成する各種ファイルは、ユーザー領域( ~/.cursor/skills/ )に配置されるようにしました。Cursor はこのディレクトリを自動的に走査するため、配置するだけで Skills が利用可能になります。

# Skills を管理するリポジトリで実行するだけ
./scripts/build-cursor-skills.sh

変換処理の具体例

たとえばある Claude Code Skill の SKILL.md には、以下のように GitHub API 経由でドキュメントを動的に取得する構文が含まれています。

# API設計ガイドライン

以下のガイドラインに従って API を設計してください。

!`gh api /repos/org/repo/contents/docs/web_api_design.md ...`

変換スクリプトはドキュメントを管理するリポジトリ上に配置します。こうすることで、この !gh の行をローカルにあるドキュメントの内容で置き換えることができます。

# API設計ガイドライン

以下のガイドラインに従って API を設計してください。

(ローカル参照した web_api_design.md の内容がここに展開される)

これにより、GitHub API を呼び出さなくてもドキュメントの全文がスキルに含まれるようになり、Cursor でも問題なく動作します。

動的に取得する Claude Code 形式と比較すると、ドキュメントに変更があるたびにスクリプトの再実行が必要になります。この点に関しては Claude Plugin を使っていたとしても手動でアップデート(claude plugin update <plugin>)する必要があるため、大きな差はないだろうと判断して許容しました。

出力されるディレクトリ構造

スクリプトを実行するとユーザー領域に下記のようなディレクトリ構成でファイルが展開されます。

~/.cursor/skills/
├── skill-ref-design-api/
│   └── SKILL.md          # ドキュメントが埋め込まれたスキル
├── skill-ref-design-table/
│   └── SKILL.md
├── skill-wf-design/
│   ├── SKILL.md
│   ├── intro.md
│   ├── workflow.md
│   ├── troubleshooting.md
│   └── samples/
│       └── default.md
...

Dev Container 環境への対応

変換スクリプトをリリースした後、Cursor で Dev Container を使って開発しているメンバーから「スキルが認識されない」という報告がありました。

原因はシンプルで、Dev Container 内からはホスト側の ~/.cursor/skills/ が参照できないためです。

これを解決するためにいくつかの方法を検討しました。

方法 メリット デメリット
devcontainer.json~/.cursor をマウント 設定一箇所で済む Cursor を使っていない人のホストにも ~/.cursor/ が作成されてしまう
ワークスペース直下に配置 マウント不要(ワークスペースはデフォルトでマウント済み) gitignore の設定が必要

チーム内には Cursor を使っていないメンバーもいるため、devcontainer.json にマウント設定を追加する方法は副作用が大きいと判断し、ワークスペース直下に配置する方法を選択しました。

具体的には、変換スクリプトに --target オプションを追加し、出力先ディレクトリを指定できるようにしました。

# Dev Container 環境向け:ワークスペース直下に配置
./scripts/build-cursor-skills.sh --target /path/to/repo

これにより、スキルファイルはワークスペース直下( <repo>/.cursor/skills/ )に配置されます。ワークスペースはデフォルトで Dev Container にマウントされているため、追加のマウント設定なしでスキルが認識されます。

ただし、ドキュメントが更新されてスクリプトを再実行すると、そのたびに更新された Skills を構成するファイルに差分が出てしまいます。そこで、利用する側のリポジトリでスクリプトによって配置されるディレクトリ以下を gitignore する対応も合わせて行いました。

今後の展望

現在はビルドスクリプトを手動で実行する必要がありますが、Cursor 側で Claude Plugin と同等の配布機構や !command 構文がサポートされれば、変換スクリプト自体が不要になる可能性もあります。その動向もウォッチしつつ、現時点で最もシンプルに課題を解決できる方法として、この変換スクリプトによるアプローチを採用しています。

また、元のドキュメントに更新が入った時に手元の Skills をアップデートすることを促す通知を送信するなど、ユーザーの利便性に配慮した仕組みづくりも進めていきます。

おわりに

今回は、Claude Plugin 形式で配布している Agent Skills を Cursor でも利用できるようにした取り組みをご紹介しました。

「Claude Code で便利に使っている Skills を他のツールでも使いたい、でもプラットフォームごとに構文や配布の仕組みが違って大変」というのは、多くのチームが直面しうる課題だと思います。私たちのアプローチはシンプルなシェルスクリプトによる変換という泥臭い方法ですが、低コストで確実に課題を解決できました。少なくとも今後 Agent Skills の配布の仕組みが Cursor に搭載されるまでの暫定対応としては十分に機能していると思っています。

この記事が、同じような課題に取り組む方の参考になれば幸いです。

最後までお読みいただき、ありがとうございました!

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

こんにちは、タイミーでバックエンドのテックリードをしている新谷(@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 SkillsWorkflow 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を実行すると、以下のような流れで進みます。

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

開発者はスラッシュコマンドを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で実現する試みです。

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

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

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

## 推奨アプローチ

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

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

工夫点2:ガイドラインURLの提示

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

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

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

工夫点3:抽象から具体へ段階的に

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

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

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

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

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

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

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

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

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

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

使ってみての感想

自分自身の所感

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

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

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

VPoEの反応

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

語彙力が下がっているVPoE

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

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

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

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

おわりに

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

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

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

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

product-recruit.timee.co.jp

失敗から学んだ仕様駆動開発――チームの暗黙知を形式知化した1ヶ月の実践と次の課題

こんにちは!プロダクトエンジニアのkazzhiraです。

私たちのチームでは、2025年の夏ごろから「AI活用による開発生産性の向上」に取り組んできました。しかし、当初の取り組みは抽象的なガードレールの提示や個々人の実践にとどまり、チームとして大きな成果には結びつきませんでした。

その後、SDD(仕様駆動開発)というアプローチに出会い、オープンソースの cc-sdd フレームワークをベースに試行錯誤を重ねてきました。

本記事では、AI開発標準の策定に失敗した経験から何を学び、どのように仕様駆動開発に辿り着いたのか、そして、実践を通じて得た成果と学びをご紹介します。

チームのAI導入でうまくいかなかった話

AI活用の個人最適化

当初、チームでは Cursor、Claude Code、Devin、GitHub Copilot、Gemini などの AI ツールを個々人の判断で利用できる状態でした。 しかし、AI活用の状況は個々人に閉じており、チームとしてのナレッジ共有や標準化は進んでいませんでした。

AI開発標準策定の失敗

そこで「AI開発標準」の策定を試みました。情報を収集したうえで、Planモードで実装計画を立て、途中でレビューを挟む開発スタイルを言語化しました。しかし、結果的にこの取り組みは失敗に終わりました。

  • 資料の説明が抽象的で、チームが具体的に動きようがなかった
  • 開発手法の共通項を抜き出しただけのガードレールに過ぎなかった
  • 実際の開発プロセスに落とし込めず、絵に描いた餅になった

参考:当時の考えを振り返った記事

なぜSDDをやろうと思ったのか

理想の開発体験の議論

チームで理想の開発体験・開発生産性の課題を話し合った結果、以下の課題が明確になりました。

  • リファインメント(仕様を決める会議)で議論が発散して収束に時間がかかる
  • AIは顧客課題、ユーザーストーリーを知らず、要件の精度が高くない
  • AIの出力が微妙で、整理されたコンテキストが足りない

SDDとの出会い

これらの課題を解決する方法として、SDD(仕様駆動開発)に辿り着きました。

SDDの本質は、仕様書を「単なるドキュメント」ではなく、AI と人間の両方が参照する SSoT(Single Source of Truth)として機能させることです。

  • 定性面
    • AIがユーザーストーリー、背景、受け入れ条件から精度の良い仕様書を生成する
      • →「AIは顧客課題、ユーザーストーリーを知らず、要件の精度が高くない」の解決
    • 構造化された要件定義書・設計書・開発ルールで一貫したコンテキストを提供する
      • →「AIの出力が微妙で、整理されたコンテキストが足りない」の解決
  • 定量面
    • 価値提供速度の向上

これらの効果を期待し、投機的に取り組んでみることを決めました。

ちなみに、「リファインメントで議論が発散して収束に時間がかかる」は当時Notion AIでの解決も試しました。しかし本題から外れるため、本記事では割愛します。

SDDの実践と工夫

cc-sddフレームワークの採用

SDD を実践するにあたり、私たちはオープンソースの cc-sdd(Spec-Driven Development フレームワーク)を採用しました。 深い理由はなく、筆者が各所で目にして実験的に入れていた背景があります。

チーム固有の課題

cc-sdd の基本的なアプローチを導入した上で、私たちのチームは以下の課題に直面しました。

  • 複数のリポジトリを AI が横断的に操作できない
  • チーム固有のタスク分割・実行ルールがなく、AI の出力がチームの開発フローに合わない
  • Rails 固有の設計パターンが AI に伝わらない
  • プロダクトのドメイン知識が AI に渡っていない

私たち独自のソリューション

これらの課題に対し、私たちは以下の解決策を構築しました。

1. マルチリポジトリ横断ワークスペース

Cursorによる開発を前提に、code-workspaceを生成して複数リポジトリを統合的に扱う仕組みを実装しました。

【my-team.code-workspace】

{
  "folders": [
    {
      "name": "my-team",
      "path": "."
    },
    {
      "name": "backend",
      "path": "~/workspace/backend-repository"
    },
    {
      "name": "frontend",
      "path": "~/workspace/frontend-repository"
    },
    ...
  ]
}

これにより以下のメリットが得られました。

  • AI エージェント(Cursor / Claude Code 等)がリポジトリを横断して操作可能
  • 仕様書リポジトリ(my-team)とコードベースを統合管理

私たちの最初の実装では、my-team・backend・frontendをセットで管理しました。 今はもう少し増えています。

2. タスク生成・実行ルールの整備

チーム固有のタスク生成・実行ルールを定義しました。

ルール種別 内容
タスク分割ポリシー "デプロイ可能な最小粒度" にタスク分割
Commit・Push・PRのルール 例示することで、意図した生成に誘導する。例えば "commitには変更理由とリファレンスを必ず含める"、"PRテンプレートに従う" など。
タスク実行順序の定義 Swaggerを定義してからfrontendとbackendの作業に移行する。

3. カスタムステアリングドキュメント

Rails 固有の設計パターンやプロダクトのドメイン知識をステアリングドキュメントとして整備しました。

  • Controller Patterns(before_action の濫用禁止、個別でエラーハンドリング不要など)
  • プロダクト固有の名称、用語、ユースケース
  • リポジトリ構造のサマリ
  • 採用している技術の詳細

例として「プロダクト固有の名称、用語、ユースケース」を定義した例を示します。

# Product Overview

タイミーアプリのAPIサーバー、クライアント向けWebアプリケーションのAPIサーバー、
ワーカー向けモバイルアプリケーション、社内管理ツールを提供するプラットフォーム。

## Core Capabilities

1. **ワーカー・クライアント管理**: ワーカーとクライアント企業のアカウント管理、認証、プロフィール管理
2. **求人・マッチング**: 求人作成、公開、ワーカーとのマッチング機能
3. **勤怠・給与管理**: 出勤管理、給与計算、支払い処理
4. **コミュニケーション**: チャット機能、レビュー・フィードバック機能
5. **管理機能**: 社内管理ツール、各種レポート・分析機能

## Target Use Cases

- **クライアント企業**: 求人作成・管理、ワーカー管理、勤怠確認、給与支払い
- **ワーカー**: 求人検索・応募、勤怠管理、給与確認
- **社内管理者**: システム管理、データ分析、各種レポート生成

## Value Proposition

- ワーカーとクライアント企業を効率的にマッチングするプラットフォーム
- 勤怠管理から給与計算まで一貫した業務フローを提供

4. カスタムコマンド

cc-sddのコマンド体系以外で、チームで必要な成果物を保管するためのコマンドを用意しました。内容は長いため省略します。

  • QAチェックリストの自動生成「spec-qa-checklist」
  • Playwright MCPによるQA自動実行「playwright-mcp-qa」

最終的なファイルツリーを示します。

my-team/
├── my-team.code-workspace       # マルチリポジトリ統合ワークスペース定義(独自作成)
├── repos.yml                     # 対象リポジトリ一覧(独自作成)
├── repos.template.yml            # ↑のテンプレート(独自作成)
├── docs/                         # プロジェクト横断ドキュメント
│
├── scripts/
│   ├── setup.sh                  #   初期セットアップ(独自作成)
│   ├── setup-workspace.sh        #   ワークスペース構成生成(独自作成)
│   └── sync-*.sh                 #   リポジトリ・設定の同期(独自作成)
│
├── .cursor/
│   └── commands/                 # カスタムコマンド(独自作成)
│       ├── spec-qa-checklist.md  #   QAチェックリスト生成
│       └── kiro/                 #   Kiro Spec-Driven コマンド群
│
└── .kiro/
    ├── steering/                 # アーキテクチャ制約
    │   ├── product.md            #   プロダクト原則
    │   ├── tech.md               #   技術標準
    │   └── structure.md          #   コード構造パターン
    ├── settings/
    │   ├── rules/                # 設計・実行ルール(独自)
    │   │   ├── tasks-generation.md        # タスク生成(プレフィクス規約・分割順序)(独自作成)
    │   │   └── task-execution-policy.md   # 実行ポリシー(環境・Git・コミット規約)(独自作成)
    │   └── templates/
    │       ├── specs/            #   仕様テンプレート
    │       └── steering/         #   ステアリングテンプレート
    └── specs/{feature}/          # 機能単位で生成
        ├── requirements.md       #   要件
        ├── design.md             #   設計
        ├── tasks.md              #   タスク
        └── e2e-qa-checklist.md   #   QA(独自作成)

評価

ポジティブな評価

cc-sddの短期間の導入で最も価値を感じたのは、実装速度の向上ではなく、開発プロセスの質の向上でした。

  • 暗黙知の形式知化 — これまで個人の頭の中にあった仕様判断が、requirements / design / task の3つの成果物を通して言語化・共有された
  • 手戻りの減少 — 仕様書によってコンテキストが整理されたことで、AIの出力品質が安定し、実装後の手戻りが体感として減った
  • 合意形成の質の向上 — 仕様を厳格に言語化するプロセスが、チーム内の認識齟齬を早期に解消した
  • モブワークとの親和性 — 構造化された仕様書が共通言語として機能し、スプリント初期の設計作業を効率的に進めることができた

ネガティブな評価

一方で、チームで改善すべき課題も挙がっています。

  • モノにもよるが、仕様書を作る工程で同期的に1日〜1.5日の時間を使う
  • 仕様書を精査する工程の疲労感
  • 実装スピードとデプロイ頻度は、以前と同等か、微増している感覚
  • シンプルに練度不足
  • リファインメントが引き続きボトルネック。実装が効率化しても、要求の供給が追いつかなければ全体のスループットは上がらない
  • 中間生成物のレビューがリファインメントに次ぐボトルネック。AIが高速に生成するアウトプットに対し、人間のレビューが追いつかない
  • etc.

データで見る事実:cc-sdd導入でデプロイ頻度は向上しなかった

前提として、開発者が3名のスクラムチームです。

【デプロイ頻度の移動平均推移】

デプロイ頻度の移動平均推移

開発生産性を測るFour Keysの1つの指標であるデプロイ頻度に着目しました。

  • cc-sdd導入前後でデプロイ頻度が向上していないことを観測
  • AIを本格導入してきた過去6ヶ月で見るとデプロイ頻度は増加傾向

先ほどのネガティブな評価の「実装スピードとデプロイ頻度は、以前と同等か、微増している感覚」とも一致しています。

ここで、他の視点も入れてみます。

【デプロイ頻度と変更リードタイムの移動平均推移】

デプロイ頻度と変更リードタイムの移動平均推移

【平均レビュープルリク数とレビューからアプルーブまでの平均時間の移動平均推移】

平均レビュープルリク数とレビューからアプルーブまでの平均時間の移動平均推移

【マージ済みプルリク数のアクティビティの推移】

マージ済みプルリク数のアクティビティの推移

これらの結果から、cc-sddによる開発について3つの事実が分かりました。

  • 変更リードタイムは以前の開発繁忙期の時と同程度の推移
    • ※sddに関連するドキュメント更新のアクティビティは計測対象外です
  • レビュー時間は以前よりも下がっている
  • 瞬間風速的にはPR作成数が過去半年で最多を記録した

cc-sddによって、設計からレビューの効率化には成功しているが、デプロイまでの流れを阻害しているボトルネックが別に存在すると読み取れます。 これまでの経緯を含めて考察すると、それはリファインメントによる要件の供給速度だということがわかります。

今後の取り組み

ここまでの取り組みでは事実としてデプロイ頻度が上がりませんでした。 ネガティブな評価であがった課題を “のびしろ” と捉え、インパクトの大きい課題をコツコツ解消していく予定です。

直近では、AI-DLCのアプローチとスクラム開発と組み合わせ、リファインメントを改善する方針で以下の取り組みを進めています。

  • AIを要求・デザインフェーズにも適用し、仕様策定のボトルネックを解消する
    • 仮説の壁打ち
    • プロトタイプ作成を回す
  • AIがアクセス可能なSSoTの範囲拡充(ビジネスコンテキスト、ユーザーリサーチ等)
  • 価値提供のフィードバックループを短縮し、次の要求定義に繋げる

まとめ

cc-sddの導入で仕様の認識齟齬が早期に解消され、意図した仕様どおりの実装に到達しやすくなりました。 しかし世間で語られるようなAIによる劇的な生産性向上には至っていません。 仕様策定フェーズのボトルネックやレビュー負荷など、AIを適用できる余地は多く残されています。 私たちのチームでは、思考をAI Drivenに変化させ、要求定義から価値提供までの全体フローを、改めてAI前提で組み直す必要があることが見えてきました。

この記事を書いている時点でも新たな取り組みで急速に進化していることを実感しています。 私自身も置いていかれないように、チームに貢献できるように成果を出し続けようと思います。 引き続きこの領域に挑戦していきます。

タイミーには、こうした挑戦と学び、そして発信を歓迎する文化があります。 ともに挑戦し成長していきたい方、興味があればぜひ1度お話ししましょう!

プロダクト採用サイトTOP

カジュアル面談申込はこちら

Elasticsearchのインデキシングから検索までの仕組みを図解してみた

はじめに

こんにちは。プラットフォームエンジニアリングチームに所属している徳富(@yannKazu1)です。

先日、本番環境でドキュメントの大規模更新を行った際にCPUが100%に張り付く事象が発生しました。検証環境で同じ更新処理を試しても再現せず、原因がわからない。そこで「そもそも自分、Elasticsearchの中で何が起きてるかちゃんと理解してないな」と気づき、インデキシングから検索までの仕組みを一から整理してみました。

同じように「なんでこうなるの?」と悩んでいる方の助けになれば嬉しいです。

前提知識

本記事では、Shard内部の動作にフォーカスして説明していきます。「そもそもShardって?Segmentって?」という方は、メルカリさんのこちらの記事がとてもわかりやすいので、先に読んでおくことをおすすめします。

全体の流れ

まず、大枠の流れを押さえておきます。

  1. インデキシング開始 — ドキュメントがメモリバッファに蓄積される
  2. Refresh — メモリバッファの内容からセグメントが作られ、検索可能になる
  3. 検索 — すべてのセグメントを対象に検索が実行される
  4. セグメントマージ — 小さなセグメントが統合され、削除済みデータも物理削除される

シンプルに書くとこれだけなんですが、それぞれの段階で「何が起きているのか」「どんな時に負荷が上がるのか」を知っておくと、トラブル時の原因切り分けがしやすくなります。

では、各ステップを詳しく見ていきましょう。

1. インデキシング開始

ドキュメントがインデキシングされると、まずメモリバッファに蓄積されます。同時に、各シャードのTransaction Log(translog)にも操作が記録されます。

Lucene commitは変更のたびに実行するとコストが高すぎるため、その役割をtranslogが担います。万が一プロセスの終了やハードウェア障害が発生しても、translogから操作を再生することでデータを復旧できます。

なお、デフォルト設定(index.translog.durability: request)では、各リクエストごとにtranslogへのfsyncが発生するため、ディスクI/Oが完全にゼロというわけではありません。 参考ドキュメント:

2. Refreshによるセグメント生成

デフォルトでは1秒ごとにRefresh処理が走ります。この処理で、メモリバッファの内容がファイルシステムキャッシュに書き込まれ、immutable(不変)なセグメントが新たに作られます。ここで初めて、そのデータが検索可能になります。

RefreshとFlush、何が違うの?

ここで似た名前の処理が出てくるので、先に整理しておきます。この2つ、最初は「同じようなもの?」と思っていたんですが、実は全く別の操作です。

操作 やっていること 重さ 目的
Refresh メモリバッファ → メモリ内セグメント作成(ファイルシステムキャッシュ経由) 軽め 検索できるようにする
Flush Lucene commit + translogクリア(ディスクに永続化) 重い データを永続化する

重要なのは、検索可能にするのはRefreshだけということです。Flushは永続化のための処理であり、検索可能性には影響しません。検索はメモリ内のセグメントに対して行われるため、Refreshでセグメントが作られて初めて検索できるようになります。

Flushは、translogが一定サイズに達した時や、一定時間が経過した時に発生します。

Search Idleルール

ここで重要なルールがあります。自動Refreshは、過去30秒以内に検索リクエストがあったインデックスだけが対象です(厳密にはシャード単位で管理されます)。つまり、検索トラフィックがあるシャードには定期的なRefresh(デフォルト1秒ごと)が走りますが、検索されていないシャードはバックグラウンドRefreshがスキップされ、リソースが節約される仕組みになっています。これはバルクインデックス時のパフォーマンス最適化を目的とした機能です。

「Refreshがスキップされている間に追加されたデータはどうなるのか」と疑問に思われるかもしれませんが、心配は不要です。アイドル状態のシャードに検索リクエストが来ると、その検索操作の一部としてRefreshがトリガーされ、完了してから検索結果が返されます。つまり、データ自体は問題なく検索できます。ただし、アイドル状態からの最初の検索はRefresh完了を待つ分、レスポンスが遅くなる可能性がある点には注意が必要です。

とはいえ、本番環境と検証環境では動きが変わってくる可能性がある点がポイントです。本番では常にユーザーが検索しているので定期Refreshが走ります。しかし検証環境では誰も検索していない場合、シャードがアイドル状態になり、検索時に初めてRefreshが走ります。同じ更新処理でも、裏側で起きていることがまったく異なる場合があります。

Refresh間隔は調整できます

index.refresh_interval で設定可能です。大量データを投入する時は、この値を大きくしておくとセグメント数を減らすことができます。なお、アイドル判定の時間は index.search.idle.after(デフォルト30秒)で変更できます。

PUT /my-index/_settings
{
  "index": {
    "refresh_interval": "30s"
  }
}

参考ドキュメント:

短期間に大量更新すると何が起きるか

さて、ここからが本題です。短期間に大量の更新が発生すると、Refreshのたびに小さなセグメントがどんどん作られていきます

セグメントはimmutableなので、「既存のセグメントにちょっと追加」ということができないんです。更新のたびに新しいセグメントを作るしかない。結果として、細かいセグメントが山のように溜まっていきます。

これが引き起こす問題

  • セグメントが増えると検索が遅くなる
  • ファイルディスクリプタをたくさん消費する
  • 後で説明するマージ処理の負荷が大きくなる

対策

大量にインデックスする時は refresh_interval-1(無効)にしておいて、終わったら手動でRefreshする。これだけでだいぶ違います。

参考ドキュメント:

削除処理の仕組み

ドキュメントを削除する時、実際にデータを消しているわけではありません。セグメントがimmutableである以上、「この部分だけ消す」ができないんです。

じゃあどうするかというと、削除フラグ(tombstone)を付けて「削除済み」とマークするだけ。いわゆる論理削除ですね。

実際の流れ

  1. 削除リクエストが来る
  2. 対象ドキュメントに削除フラグを付ける
  3. 検索時はフラグ付きのドキュメントを結果から除外する
  4. 後でセグメントマージが走った時に、やっと物理的に削除される

つまり、削除したつもりでもマージが完了するまでディスク容量は減らないんです。「削除したのに容量減らないな...」と思ったことがある方、これが原因かもしれません。

参考ドキュメント:

3. 検索時に何が起きているか

検索処理では、すべてのセグメントに対して検索が実行されます。各セグメントの結果をマージして、最終的な検索結果ができあがります。

ここで「セグメントが増えると検索が遅くなる」理由がわかりますよね。検索対象が増えれば増えるほど、当然時間がかかります。

キャッシュの話も重要です

Elasticsearchには主に2種類のキャッシュがあるんですが、どちらもセグメントの変更に影響を受けます。

キャッシュ 単位 いつ無効化される?
Node query cache セグメント単位 セグメントがマージされた時
Shard request cache シャード単位 シャードがリフレッシュされた時

新しいセグメントにはまだキャッシュがないので、最初のクエリは必ずキャッシュミスになります。しかもマージが走るとせっかく溜めたキャッシュも消えてしまう。

セグメントが頻繁に作られたりマージされたりする環境では、キャッシュがなかなか効かなくなります。

参考ドキュメント:

4. セグメントマージ — 重い処理

バックグラウンドで定期的にセグメントのマージ処理が走ります。小さなセグメントをまとめて大きなセグメントにする処理です。この際、転置インデックスの再構築が行われるため、CPUとI/Oを大量に消費します。

マージがもたらすメリット

  • 細かいセグメントが大きなセグメントに統合されます
  • 削除フラグ付きのドキュメントが物理削除されます
  • セグメント数が減るため、検索が高速化します

ただし、マージ中は重い

マージ自体はとても重い処理です。マージが走っている間は、検索もインデキシングも影響を受けます。

ElasticsearchにはAuto-throttling(自動スロットリング)という仕組みがあり、マージがインデキシングに追いつけなくなると、インデキシング自体にブレーキがかかります。これは「セグメント爆発」を防ぐための安全装置です。

セグメントマージがどんな感じで進むのか、視覚的に理解したい方はこちらの記事がおすすめです。

参考ドキュメント:

まとめ

長くなりましたが、ここまで読んでいただきありがとうございます。

今回学んだことで特に大事だなと思ったのは、この3つです。

  1. セグメントはimmutable — 更新・削除のたびに新しいセグメントができる
  2. Refreshの30秒ルール — 検索がないシャードはRefreshがスキップされる
  3. マージは重い — CPU・I/Oを大量に使い、キャッシュも無効化される

本番環境で「なんか重いな」と思った時は、セグメントの状態やマージの発生状況も見てみてください。きっと何かヒントが見つかるはずです。

もし同じような問題で悩んでいる方がいたら、この記事が少しでも参考になれば嬉しいです。

ちなみに、今回の調査をきっかけに、チームメンバーがElasticsearchの詳細な状況を収集できる仕組みを整えてくれました。実際のデータをもとにした分析や考察、情報収集するための観点や方法については、そのメンバーが続編で紹介してくれるかもしれません。お楽しみに!

pmconf2025に参加してきました part3

タイミーのプロダクトマネージャーの飯田です。

今回は、12/4に開催されたプロダクトマネージャーカンファレンス(以下pmconf)に参加してきました。このイベントを通じて非常に有意義な学びを得られたため、タイミーのプロダクトマネージャー(柿谷、小宮山、鈴木、小西、佐々木、楠本、飯田)から、各セッションから学んだ内容を、全3回の記事で紹介します。

(本記事は、全3回のうち、Part3です。)

▪️Part1・Part2はこちら

pmconf2025に参加してきました part1

pmconf2025に参加してきました part2

マルチプロダクトのカオスを制す。「プロダクトディシジョンレコード」で実現するチーム横断のアラインメント戦略

登壇者:

株式会社エス・エム・エス / プロダクト推進本部 アーキテクト プロダクトマネージャー

三浦 玄 氏

登壇資料:

speakerdeck.com

株式会社エス・エム・エスで「カイポケ」のリニューアル責任者を務める三浦氏による、不確実性の高いマルチプロダクト開発における意思決定プロセス「プロダクトディシジョンレコード(PDR)」についてのセッションをレポートします。

■ マルチプロダクトにおける「不確実性」の正体

カイポケは40以上のサービス・プロダクトを展開する巨大なバーティカルSaaSで、業務×業態の掛け合わせによる複雑性(カオス)を抱えています。複数のプロダクト連携を前提とした「カイポケコネクト」の開発では、将来の予測の将来予測の困難さ(環境の不確実性)や、誰に何を聞けばよいか分からないこと(通信の不確実性)が課題となり、「誰が決めるのか?」「もう決まったのか?」といった混乱が生じていました。

■ 意思決定のプロトコル「プロダクトディシジョンレコード」

この不確実性の中で意思決定を機能させるプロトコルとして設計されたのが「プロダクトディシジョンレコード(PDR)」です。元々はエンジニアリングの文脈であるArchitecture Decision Record(ADR)をベースにしており、決定内容だけでなく、「なぜその決定に至ったのか」という背景や文脈(コンテキスト)を残すことを重視しています。

テンプレートには以下の項目が含まれます:

  • イシューとコンテキスト: 白黒ついていない問題と、なぜ今それを解決するのか。
  • クリティカルユーザージャーニー: 影響を受けるUX/CUJ。
  • オプションと評価軸: 選択肢のメリット・デメリットと、判断のためのトレードオフ基準。
  • 決定と理由: 最終的な結論と、その選択理由。

■ 運用と定着のポイント

PDRは単なるドキュメントではなく、会議体のアジェンダと連動させ、Slackへのプッシュやロードマップへの反映を行うサイクルで運用されています。特に「影響範囲が広く不可逆な決定」や「重要なリリース前の意思決定」において、WIP(書き途中)の段階から透明性を確保しながら合意形成を図る点が重要です。

■ 参加して感じたこと

「決定をデータベース化し、一覧性の高い形で見える化する」というアプローチは、シンプルながらも実行難易度が高い取り組みだと感じました。

しかし、不確実性が高い環境だからこそ、当時の意思決定の背景(コンテキスト)が資産として残ることの価値は計り知れません。小規模なチームから大規模・部署横断のプロジェクトまで、規模を問わず汎用的に活用できるフレームワークであり、自組織でも取り入れていきたいと感じました。

(執筆:楠元久貴)

元経営企画CSO(戦略責任者)のPMが語る「プロダクトが創る事業戦略」のリアル  〜PLに振り回されず、価値から逆算する事業貢献の最大化〜

登壇者:

キャディ株式会社 / VPoPS(Product Strategy)

岸本 裕史 氏

登壇資料:

speakerdeck.com

いわゆる「ビジネス価値と顧客価値のトレードオフ」や「よりビジネス観点を持ちたい」という課題感からこちらのセッションに参加しました。

PMを苦しめる「PL責任論」

PMの現場では、往々にして以下の対立構造が生まれます。

  • PMの想い: 「ユーザーのために価値あるプロダクトを作りたい(中長期視点)」
  • 経営・事業側の要求: 「今月の売上はどうするんだ(短期視点)」

この板挟みになり、PL達成のために本質的でない機能開発に追われてしまうのが「PMあるある」です。岸本さんはこれを、単なるコミュニケーション不足ではなく、見ている指標と時間軸のズレによる構造的な問題だと指摘しました。

視点を変える3つのポイント

1. 売上は「遅効性指標」である

経営企画や経営陣にとって、売上などの財務数値はあくまで「結果(遅効性指標)」に過ぎません。 経営者が真に見極めたいのは、すでに起きた結果ではなく、「隠れた未来(先行指標)」です。プロダクトが本質的な価値を提供できているかどうかが、将来の売上を作る先行指標となり得ます。

2. 指標を見る「順序」を変える

「売上を作るためにプロダクトを作る」のではなく、「市場(TAM/SAM/SOM)という大きなポテンシャルから逆算し、価値提供の進捗を確認する」というアプローチへの転換が提案されました。

  1. TAM/SAM/SOMを見据える: まず自分たちが戦っている市場の全体像とポテンシャルを定義する。
  2. 価値の開拓スピードを確認する: その巨大な市場に対して、プロダクトがどの程度のスピードで価値を届けられているかを測定する。
  3. 結果として売上を見る: 上記の結果としてついてくる数字として売上を捉える。

この順序でロジックを組むことで、「短期的な売上」という小さな枠組みではなく、「巨大な市場を取りに行くための投資」という文脈でプロダクト開発を語れるようになります。

3. 事業戦略とは「価値から逆算すること」

キャディ社の事例(製造業2,000兆円市場への挑戦)を挙げながら、産業全体の課題(Issue)からTAMを規定し、そこから逆算して現在のプロダクト戦略を描く重要性が語られました。 PLに振り回されるのではなく、PL(結果)をコントロールするための変数が「プロダクト価値」であると定義し直すことが、戦略的PMへの第一歩とのことです。

感想

「売上は遅効指標でプロダクト価値がその土台である」というのは、言われてみれば当たり前のことです。一方で、実務でその考え方に基づいた判断ができていたかというと、そうではなかったと感じました。

PLを意識して小手先の取り組みに終始したことがある反省があります。

それを踏まえて今後は市場と顧客を深く理解し、価値をベースにプロダクトの展望を大きくかつ根拠を持って語れるようにしていかねばと思いました。

(執筆:小西 裕真)

「PMが未来に挑む、って何?──変化の時代に“対話”で未来を描く」

登壇者(インナーサークル):

株式会社TVer / サービスプロダクト本部プロダクト推進部部長

松岡 綾乃

BASE株式会社 / 執行役員 BASE BANK 事業 事業責任者

柳川 慶太

PM Jam / プロダクトマネージャー

飯沼 亜紀

ファシリテーター:

Product People Inc. / 提携プロダクトコーチ

広瀬 丈 氏

「PdMの未来」を問う、熱気ある1時間45分

〜フィッシュボウル形式で議論された「PM不要論」と「本質的な役割」〜

OSTの裏側では、「PMの未来」をテーマに、参加者同士が対話を行う「フィッシュボウル」形式でのディスカッションを実施していました。

■ 議論のテーマと形式 当初のテーマは「PMの未来」でしたが、議論は「そもそもPMはいらないのでは?」という、より根源的かつ挑発的な問いからスタートしました。フィッシュボウルという発散型の大規模対話手法を用いることで、予定されていた1時間45分は、フェーズや立場の異なる参加者たちによる濃密な議論の場となりました。

■ さまざまなトピック 議論の中では、プロダクトマネジメントの役割の曖昧さや多面性について、以下のような視点が飛び交いました。

  • 事業フェーズによるPMの役割変遷
  • 経営層と現場をつなぐ「結節点」としての機能
  • 「なぜビジネスサイドでは代替できないのか?」という問い
  • 経営者・事業責任者とPdMの境界線

■ 印象的な議論:「ロードマップを書いて捨てる!」 その中でも印象に残ったトピックの一つが、「ロードマップは書いて捨てる!」という一言から始まった、不確実性の高い現代におけるロードマップのあり方です。

議論の中では、不確実性の高い時代において「固定化はリスクである」という認識のもと、状況に合わせて適切にロードマップを書き換え、何が最善かを考え抜くことの重要性が語られました。

しかし、単に書き換えるだけでは短期的な施策に終始してしまう懸念もあります。そのため、2-3年後を意識し現在地を把握しながら、今の状況に必要な意思決定をしていく視座が求められます。

これには、PMには計画策定能力だけでなく、状況に応じた意思決定力や、ステークホルダーへの説明責任、適切なコミュニケーションなどの総合的なスキルが求められると気付きました。

単に「PMとは何か」を定義するのではなく、変化の激しい時代において「どのような視座でプロダクトや組織に向き合うべきか」を再考させられる、非常に示唆に富んだセッションとなりました。

(執筆:飯田 咲紀)

おわりに

全3回にわたり、pmconf2025のセッションレポートをお届けしました。 計7名のPMで参加した今回のカンファレンス。各セッションを通じてさまざまな学びが得られました。

「売上はプロダクト価値の遅効指標である」という言葉の通り、私たちが向き合うべきは常に「ユーザーのペイン」と、その先にある「市場への価値提供」です。

今回得た熱量と知見を日々の開発に還元し、タイミーはこれからも「はたらく」のインフラとして、ユーザーの皆様に驚きと信頼を届けるプロダクトをつくり続けていきます。

さいごに、pmconfではブースも出展していましたが、タイミーでは、共に「はたらく」の未来をつくる仲間も募集しています。興味を持っていただいた方は、ぜひカジュアルにお話ししましょう!

(執筆:飯田 咲紀・タイミーPM一同)

pmconf2025に参加してきました part2

タイミーのプロダクトマネージャーの飯田です。

今回は、12/4に開催されたプロダクトマネージャーカンファレンス(以下pmconf)に参加してきました。このイベントを通じて非常に有意義な学びを得られたため、タイミーのプロダクトマネージャー(柿谷、小宮山、鈴木、小西、佐々木、楠本、飯田)から、各セッションから学んだ内容を、全3回の記事で紹介します。

(本記事は、全3回のうち、Part1です。)

▪️Part1・Part3はこちら

pmconf2025に参加してきました part1

pmconf2025に参加してきました part3

「語られた戦略」を「語れる戦略」へ──共通言語をつくるPdMの試み

登壇者:

株式会社コドモン / 開発本部プロダクト企画部長

重山 由香梨 氏

登壇資料:

speakerdeck.com

戦略の「ズレ」を「納得感」に変える。コドモンが実践する「戦略の再編集」というアプローチ

「経営と現場の距離が埋まらない」「戦略を共有したはずなのに、メンバーの動きがバラバラ」。 組織が成長する過程で必ずと言っていいほど直面するこの課題に対し、株式会社コドモンが実践している「戦略を再編集するプロセス」についてのセッションをレポートします。

■ そもそも「戦略のズレ」はなぜ起きるのか?

セッションの中で印象的だったのは、「ズレが生じるのは当然のことであり、むしろ土台として避けられない」という前提です。同じ戦略を語っていても、立場によって見ている景色が全く異なるからです。

  • 事業・経営: 事業成長、収益性、社会的インパクト
  • プロダクトマネージャー(PdM): 価値の体系化、ユーザー体験のロジック
  • 開発: 実現可能性、負荷、品質、安全性

どれも正解であり、正しい視点です。しかし、同じ言葉を使っていても、立場に加えて在籍歴や背景知識の違いによって解釈の「ゆがみ」が生じます。その結果、現場のモヤモヤとして蓄積されてしまいます。

■ 解決策は「ズレ」を材料にした「再編集」

登壇では、このズレを「埋める」のではなく「ズレを材料にして戦略をアップデート(再編集)する」というアプローチを紹介されていました。

特に興味深かったのが、「メンバー自身が話者になる想定で読み合わせる」というプロセスです。

  • 人は「聞く立場」にいる限り、受動的・批判的になりがち。
  • しかし、自分が誰かに説明する「話者」の視点に立つことで、「どこが曖昧か」「どこが説明しにくいか」がメタ認知され、自分自身の理解不足(ズレの正体)が手元でクリアになる。

このプロセスを経ることで、トップダウンの戦略が、現場の言葉を内包した「ボトムアップ的な戦略」へと再編集されていきます。人に説明しながら理解を深める、いわゆるファインマンテクニックに近い進め方で、そこで生まれた認知のズレを材料に共通認識を再構築していく点が、とても興味深かったです。。

■ なぜ、ここまで「対話」にコストをかけるのか?

「なぜそんなに時間をかけるのか?」という問いに対し、登壇者の方は「戦略は仲間のためでもあるから」と語られていました。

ズレを放置することは、組織の中に「負の遺産」を積み重ねるのと同じです。戦略を自分事化し、自分の言葉で語れる状態にすることは、メンバーが誠実に仕事に向き合うための前提条件となります。お話を伺う中で、色々過去に色々なズレで悩んだ経験がフラッシュバックしてきました。

■ 参加して感じたこと:開発チームへの応用

このセッションを聴いて、これは組織戦略だけでなく、開発チームで新しい技術的挑戦やプロセス改善を行う際にも非常に有効だと感じました。

  • 心理的安全性を確保しながら「なぜこれをやるのか」というモヤモヤを出し切る
  • メンバー自身が「他チームに説明するなら?」という視点でワークを行う
  • 出た違和感を反映して、取り組みの進め方を再編集する

「ズレ」を否定せず、それをより良い形にするための「インプット」として捉える。そんなしなやかな組織運営のヒントをいただいたセッションでした。

(執筆:柿谷樹)

"主観で終わらせない"定性データ活用 ― プロダクトディスカバリーを加速させるインサイトマネジメント

登壇者:

株式会社カミナシ / プロダクト本部 プロダクトマネージャー

右田 涼 氏

登壇資料:

speakerdeck.com

このセッションでは、定性データを「感想」で終わらせず、プロダクトの意思決定につなげるための考え方と実践が、体系的に整理されていました。

ユーザーインタビューや現場ヒアリングは、多くのプロダクトチームで行われていますが、

  • 解釈が個人に閉じてしまう
  • チームに共有されず、再利用されない
  • 「いい話だった」で終わってしまう

といった課題を抱えやすい領域でもあります。本セッションは、そうした定性データ活用のつまずきどころを明確に言語化していた点が印象的でした。

■ なぜ定性データは「主観」で終わってしまうのか?

セッションで語られていたのは、定性データの問題は「質」ではなく、扱い方の構造にあるという視点です。

  • 事実(ユーザーの発話・行動)
  • そこから得た気づきや仮説
  • 意思決定に使われるインサイト

これらが混ざったまま扱われることで、

「誰の解釈なのか分からない」「再検証できない」状態が生まれてしまう、という指摘には強く納得感がありました。

■ 解決策は「インサイトマネジメント」

この課題に対し紹介されていたのが、

事実 → 解釈 → インサイトを明確に分離し、インサイトをチームの資産として管理する

という「インサイトマネジメント」の考え方です。

単発のインタビュー結果を結論にするのではなく、

複数の事実を束ね、再現性のある形で整理することで、

初めてプロダクトディスカバリーのスピードと質が上がる、というメッセージが一貫して語られていました。

■ 参加して感じたこと

「定性データは感想ではなく、意思決定の材料である」という言葉が特に印象に残りました。

インタビューを実施すること自体が目的化しがちな中で、

どうすればチームで使える知見に昇華できるのかを改めて考えさせられる内容でした。

日々ユーザーの声に触れているPdMにとって、

定性データ活用を一段引き上げるためのヒントが詰まったセッションだったと思います。

(執筆:小宮山貴大)

なぜ使われないのか?──定量×定性で見極める本当のボトルネック

登壇者:

株式会社カケハシ / AI在庫管理 プロダクトマネージャー

梶村 直人 氏

speakerdeck.com

本セッションでは、「なぜ使われないのか?」というPdMであれば一度は直面する問いに対し、 定量データと定性データを組み合わせて真のボトルネックを見極める考え方が整理されていました。

ファネルや利用率などの定量データを見ることで、

「どこで使われていないか」は把握できます。一方で、その背景にあるユーザーの判断や迷い、業務上の前提は、数字だけでは捉えきれません。本セッションでは、そうした定量だけ・定性だけでは見えない課題に正面から向き合っていた点が印象的でした。

■ 「使いやすい」と「使われる」は別物

特に印象に残ったのは、

「“使いやすい”(迷わず操作できる)と“使われる”(安心して業務を任せられる)は別物である」

という指摘です。

操作性を高めることで「使える」状態は作れても、それだけで業務を任せてもらえるとは限りません。業務を任せるという行為は、業務上のリスクを引き受けることや、これまでの判断基準・やり方を手放すことを意味します。そのため、操作性とは異なる次元のハードルが存在するという整理に強い納得感がありました。

■ 定量×定性で、N1の判断構造を捉える

本セッションでは、

定量であたりをつけ、定性でN1(個別ユーザー)の判断背景を深掘る

というアプローチが紹介されていました。

ユーザーに直接理由を聞くだけでは表面的な回答に留まりがちな中で、

事前に定量・定性の両面から仮説を立てた上でヒアリングに臨むことで、

ユーザー自身も言語化できていなかった前提や、店舗属性ごとの運用の違いが見えてくる、という話が印象的でした。

■ 参加して感じたこと

「使われない理由」を機能やUIの問題に矮小化せず、

ユーザーがどんな判断をし、何に不安を感じているのかまで踏み込んで理解することの重要性を改めて感じました。

定量・定性を往復しながらN1を丁寧に見る姿勢は、

プロダクトディスカバリーの質を大きく左右するのだと思います。

日々データを扱うPdMにとって、自分の分析スタンスを見直すきっかけになるセッションでした。

(執筆:小宮山貴大)

Part3に続く。

▪️Part1・Part3はこちら

pmconf2025に参加してきました part1

pmconf2025に参加してきました part3