非定型なドキュメントを効率よくリファクタする 〜えぇ！？仕様書27本の移行が1日で終わったって！？〜

リファクタリングのためのトークン節約術 Night のLT資料です
https://findy.connpass.com/event/399033/

1. 非定型なドキュメントを効率よく リファクタする 〜えぇ！？仕様書27本の移行が1日で終わったって！？〜 2026/07/16 リファクタリングのためのトークン節約術 Night 株式会社TOKIUM Webエンジニア 坂上 晴信
2. 坂上 晴信 Harunobu Sakaue 経歴 1995年生まれ。東京の離島・伊豆大島出身。 エンジニア → DevHR（= 開発組織専任の人事）→ エンジニア 2016年 3月 東京高専 情報工学科卒 2016年 4月 株式会社TOKIUM 入社 Android/Webエンジニア 2023年 1月 DevHRにロールチェンジ 育成・組織づくり・採用広報 2025年12月 再びエンジニアにロールチェンジ Webエンジニア NOW! 自己紹介 / リアルのすがた ⚫︎ ⚫︎ ⚫︎ ⚫︎ ⚫︎ 2
3. にしこりさぶろ〜 @subroh_0508 好きなもの Kotlin / アイドルマスター / ラブライブ！ Kotlin本体へのContribute経験、Kotlin Festへの複数回の 登壇経験アリ。DevHR時代も趣味でKotlinを書き続け、 "200名収容の会場で技術登壇をした人事"になった。 プライベートでは、アイマスPとライブライバーを兼任。 『シャニマス』三峰結華と『蓮ノ空』村野さやかが 人生のロールモデル。 自己紹介 / インターネットのすがた 3
4. 僕がリードする新規開発PJで、最近 「仕様ドキュメントのリファクタリング」 を実施 なぜ実施したのか？ どのように進めたのか？ トークン効率を高めるTips 今日話すこと 4
5. 前提: 仕様駆動（Spec Driven）ライクな開発 要件定義や設計方針を Markdown に起こしてバージョン管理 その Markdown を正として、コーディングエージェントに実装 させる 5
6. しばらくイイ感じに運用できていたが、次第に課題も顕在化 実コードとの整合性 仕様書に サンプルコードを直接記述 していた → 実装との整合性維持 に工数がかかる → Lintやテストを通らないコードが蓄積 仕様の網羅性 要件定義書と設計書の 役割分担が不明瞭 → どこに何を書くべきか が定まらない → 結果として、仕様の漏れが多発 前提: 仕様駆動（Spec Driven）ライクな開発 6
7. しばらくイイ感じに運用できていたが、次第に課題も顕在化 実コードとの整合性 仕様書に サンプルコードを直接記述 していた → 実装との整合性維持 に工数がかかる → Lintやテストを通らないコードが蓄積 仕様の網羅性 要件定義書と設計書の 役割分担が不明瞭 → どこに何を書くべきか が定まらない → 結果として、仕様の漏れが多発 これを解決すべく、仕様ドキュメントのフォーマットを刷新！ 実際に AIレビューの指摘数を減らせた！ 仕様ドキュメントには、具体のコードを一切書かないこととした（= 言語非依存の原則） 2段構成（要件 / 設計）→ 3段構成（要件 / 基本設計 / 詳細設計）に変え、セクションごとの記載内容を きっちり定めた 前提: 仕様駆動（Spec Driven）ライクな開発 6
8. 前提: 仕様駆動（Spec Driven）ライクな開発 新しいフォーマット最高！ これで生産性も品質も上げてくぞ！ 7
9. 前提: 仕様駆動（Spec Driven）ライクな開発 新しいフォーマット最高！ これで生産性も品質も上げてくぞ！ 古いフォーマットの仕様書、 全部で27本 あるから 忘れずリファクタしてね 因みに 人間が丁寧に進めると 40人日以上かかる から覚悟してね 7
10. 前提: 仕様駆動（Spec Driven）ライクな開発 新しいフォーマット最高！ これで生産性も品質も上げてくぞ！ 古いフォーマットの仕様書、 全部で27本 あるから 忘れずリファクタしてね 因みに 人間が丁寧に進めると 40人日以上かかる から覚悟してね 2ヶ月消えるのわろた＼(^o^)／ 7
11. フォーマットの刷新によって、AIレビュー指摘数の減少を確認 生産性の向上のためにも、新フォーマットを全面的に使っていきたい 有効な仕様ドキュメントが 27本 も存在、人力リファクタは非現実的 リファクタは一気に進めてしまい、新旧フォーマットの 併存期間を 可能な限り短く したい 仕様書リファクタ：やりたいこと & 制約 AIパワーを使って、イイ感じにやるぞ 8
12. やることを絞る 検証をシンプルに作る 単純作業は軽量モデルに任せる 仕様書リファクタ：どう進めたか？ 9
13. 「リファクタリング」の定義に沿って、やることを絞る martinfowler.com - Definition Of Refactoring やることを 「旧 → 新へ、情報を欠落なく再配置する」 ことだけに絞った Pull Requestでは 「リファクタ前後で情報が欠けていない」 ことだけを検証すると決めた やることを絞る Refactoring (verb): to restructure software by applying a series of refactorings without changing its observable behavior. リファクタリング（動詞）： ソフトウェアの外部から観察可能な動作を変更することなく、 一連のリファクタリングを適用してソフトウェアの構造を再構築すること。 “ 10
14. 「リファクタリング」の定義に沿って、やることを絞る martinfowler.com - Definition Of Refactoring やることを 「旧 → 新へ、情報を欠落なく再配置する」 ことだけに絞った Pull Requestでは 「リファクタ前後で情報が欠けていない」 ことだけを検証すると決めた やることを絞る Refactoring (verb): to restructure software by applying a series of refactorings without changing its observable behavior. リファクタリング（動詞）： ソフトウェアの外部から観察可能な動作を変更することなく、 一連のリファクタリングを適用してソフトウェアの構造を再構築すること。 “ コード生成の品質向上は要らないんですね！ 再配置だけなら、 40人日超 → 10人日 くらいに減りますね！ （心の声）適当こきやがって… 10
15. 新旧フォーマットの各セクションに対して マッピング表を作成 用語や粒度の変更は許容 内容が引き継がれていればOKとした 新旧フォーマット間で噛み合わない記述は 別ファイルに Gap として記録 やることを絞る 11
16. 静的検証 パターンマッチ ：具体のコードが新フォーマットに書かれていないか、機械的に検証 AIによる内容検証 ：旧 → 新で内容が保全されているか、セクションごとに検証 動的検証 旧仕様書 / 新仕様書、それぞれから 実装計画とコードを生成 して比較 実装計画の受け入れ条件、条件分岐や状態遷移、異常系、境界値 etc. の差分をチェック セクション・ファイルを跨いで内容が保全されているか、検証 検証をシンプルに作る 12
17. 執筆の作業は軽量モデル、タスクの実行制御と検証は高性能モデルに任せる Markdownの執筆作業 Claude Sonnet 比較的単純、かつ量が膨れやすい 実行制御・検証・マージ判定 Claude Opus タスク実行の安定性、生成物の品質を決める 単純作業は軽量モデルに任せる 13
18. 開始日時：06/18 11:30ごろ いざ実行！ なかなか丁寧に準備したけど、 全数リファクタは数日かかるかなぁ 14
19. 開始日時：06/18 11:30ごろ 終了日時：06/18 23:30ごろ いざ実行！ なかなか丁寧に準備したけど、 全数リファクタは数日かかるかなぁ 1日で終わって草 殆ど介入なしで完走したし、トークンも 週次制限の20%消費くらいで収まった 14
20. "高性能モデルとともに" やることを明確化し、業務フローを設計する 今回の仕様書リファクタのために2つSkillsを作成、いずれもClaude Opus製 業務フロー設計において、人間はAIに敵う余地がないので（評価以外は）任せましょう "高性能モデルに解かせたい" 場所を探し、そうでない場所はスクリプトでの解決を試みる 「高性能モデル」と「スクリプト」があれば、人類が思いつくほぼ全ての課題は解ける 性能評価の仕組みまで作った後で、段階的にモデルを軽量にしていくのが正攻法？ トークンを効率良く成果につなげるためには？（ポエム） 15
21. "高性能モデルとともに" やることを明確化し、業務フローを設計する 今回の仕様書リファクタのために2つSkillsを作成、いずれもClaude Opus製 業務フロー設計において、人間はAIに敵う余地がないので（評価以外は）任せましょう "高性能モデルに解かせたい" 場所を探し、そうでない場所はスクリプトでの解決を試みる 「高性能モデル」と「スクリプト」があれば、人類が思いつくほぼ全ての課題は解ける 性能評価の仕組みまで作った後で、段階的にモデルを軽量にしていくのが正攻法？ トークンを効率良く成果につなげるためには？（ポエム） モデル選択に悩む前に、まずは タスクを完遂させることが重要！（な気がする） 一度完遂させることができれば、業務フロー改善の過程で自然と適切なモデルが選べる（はず） ※非効率でもまずはタスクを終わらせ、評価と改善が可能な状態を作るのが先なのでは？という主張 15
22. 要件定義書・設計書のような 非定型でテストがしづらいドキュメント でも、 適切なタスク定義 ができればリファクタすることができる 効率よりもまず、要求品質を満たしつつタスクを完遂する ことが重要 要求品質や完了条件 = 制約が分かれば、効率化の余地も自ずと見える 業務フローの設計には、限界まで高性能モデルを使い倒すことが吉 人間は、 成果物評価の仕組み構築 と タスク実行の監視 に注力 まとめ 16
23. 資料公開＆技術発信は公式Xから 本日のスライドは公式Xで公開！ 開発チームの技術やイベント情報を 発信中、フォローお願いします！ @TOKIUM_Dev 情報発信中！ 17