MCP Commit Story: Your Engineering Journey, Remembered

MCP Commit Story：記憶に残る、あなたのエンジニアリングの歩み

MCP Commit Story とは？

MCP Commit Story は、何を作ったかだけでなく、どんな気持ちで取り組み、なぜそれが大切だったのかも記録したい開発者のための、個人的なエンジニアリング日誌です。

開発の背後にあるストーリーを大切にする開発者が、開発者のために作っている、開発中のツールです。

MCP Commit Story は、AI エージェントと連携して動作するよう設計された Model Context Protocol（MCP）サーバーとして稼働します。エージェントは、開発ワークフローから実際の背景情報を収集・要約し、日誌の記録が常に実際に起きたことに基づくよう支援します。

---

なぜ作るのか？

開発者は、何に苦労し、何を学び、どう成長したのかなど、仕事の背後にある「なぜ」を忘れがちです。
MCP Commit Story は、次のことを支援します。

• ストーリーを記録する： 各コミットが日誌の記録になり、技術的な変更だけでなく、その過程での判断、もどかしさ、ささやかな成功も記録します。
• そのときの気持ちを思い出す： 日誌には気分や感情の背景も含まれるため、何をしたかだけでなく、どんな経験をしたのかも振り返れます。
• ストーリーや気づきを見つける： ワークフロー（AI エージェントとのチャット、ターミナル、コードの変更、コミットメッセージ）から実際の背景情報を集めることで、苦労や成功の流れに気づけます。ブログ記事やカンファレンストークに活用したり、自分自身の成長を理解したりするのに最適です（決して小さなことではありません！）。
• 振り返りやレビューを支援する： 要約や気づきによって、振り返りや昇進の相談、特定の選択をした理由の説明がしやすくなります。

---

1日はどのようなものですか？

実際の開発データから生成された、日次要約の例を紹介します。

# Daily Summary - June 4, 2025

## Summary
June 4th was a day of strategic evolution from "making it work" to "making it production-ready" - a journey that revealed the hidden complexities of building robust systems. The day progressed from adding comprehensive MCP best practices to breakthrough insights about AI orchestration patterns, culminating in the humbling realization that AI content quality requires more sophisticated approaches than initially anticipated. This represents the classic progression from proof-of-concept excitement to production engineering reality.

## Key Insights & Breakthrough Moments
**The Production Readiness Awakening**: Creating seven new production readiness tasks revealed the gap between "functional" and "deployable." The realization that issues like stdout pollution, performance validation, and logging infrastructure could break MCP client compatibility demonstrates how production systems require thinking beyond core functionality to operational excellence.

**AI Orchestration Architecture Insight**: The breakthrough that AI Function Pattern functions needed centralized orchestration rather than individual context detection represents a significant architectural insight. The discovery that calling AI functions directly always returned stubs, regardless of context, led to the realization that AI capability needs to be handled at the system boundary rather than embedded in individual functions.

**The Quality vs. Speed Trade-off Reality**: Multiple iterative attempts to improve AI content quality revealed the fundamental challenge of building reliable AI-powered systems. The discovery that AI agents needed increasingly explicit instructions to avoid shortcuts and hallucinations shows how AI system reliability requires different engineering approaches than traditional deterministic systems.

## Strategic Thinking Highlights
**Scope Management Evolution**: The tension between "thoroughness and scope creep" when adding production readiness tasks demonstrates mature project thinking. The recognition that MVP delivery requires balancing best practices against shipping velocity shows the evolution from technical perfectionism to product delivery focus.

**Architecture Pattern Discovery**: The AI orchestration solution established a reusable pattern for building AI-powered MCP tools. Rather than trying to make every function AI-aware, centralizing AI capability at the system boundary creates cleaner separation of concerns and more maintainable systems.

## Discussion Highlights
> **Human:** "Follow this task completion workflow for the current task"

This simple instruction led to discovering the value of systematic archival processes for maintaining development velocity and system performance.

> **Human:** "CLI Architecture: You suggest extending CLI with operational commands, but our current architecture is 'setup-only CLI' per the docs"

This correction revealed the importance of architectural consistency and how easy it is to drift from established patterns when planning new features.

> **User Reflection**: "I'm not happy with the summary generated... The recency bias problem persists and the AI seems to be taking shortcuts despite explicit instructions not to."

This honest assessment captures the ongoing challenge of building reliable AI systems - the gap between what we instruct AI to do and what it actually does in practice.

## Conference Talk Material
This day perfectly illustrates the evolution from "feature development" to "system engineering." The initial excitement of implementing MCP handlers and completing features gives way to the sobering realization that production systems require comprehensive infrastructure: logging, performance monitoring, error handling, and operational tooling.

The AI orchestration breakthrough demonstrates how architectural insights often come from implementation failures rather than theoretical design. The discovery that centralized AI orchestration works better than distributed AI awareness shows how real-world constraints drive architectural evolution.

---

どのように動作しますか？

• バックグラウンドでの生成： Git のコミットをきっかけに、バックグラウンドで日誌の記録が自動生成されます。ワークフローを中断したり、待ったりする必要はありません。
• 豊富な背景情報の収集： コミットメッセージ、コードの変更、AI チャット履歴、プロジェクトの README をシステムが自動的に取得し、AI が常にプロジェクトの目標を理解できる、根拠に基づいた豊かな日誌の記録を作成します。
• インテリジェントなチャット収集： Cursor の AI チャットを使い、コミット間のすべての AI との会話を記録して、各コード変更の完全な時系列の背景情報を提供します。詳しくはチャット連携ユーザーガイドをご覧ください。
• AI の知識の保存： 開発中の AI アシスタントの気づきを記録して、今後の日誌の記録を充実させます。同じ解決策を見つけ直す手間を省き、プロジェクトとともに成長する永続的なナレッジベースを構築します。
• ユーザーによる制御： 生成は自動で行われますが、背景情報は自分で管理できます。手動で振り返りを追加したり、AI アシスタントが現在持っている知識を日誌に直接記録したりできます。
• 幻覚のない要約： 日誌に記録される内容はすべて、実際の行動や会話に基づいています。
• 気分と感情： AI エージェントへの話し方やコミットメッセージの内容から気分や口調を反映します。不満をぶつけたり、喜びを表したり、振り返ったりしたときの気持ちも、ありのままに記録されます。
• 自動要約： 日次要約は自動生成されます。パターンの発見、進捗の把握、共有する価値のあるストーリーの発見を支援する週次、月次、四半期、年次の要約も、今後追加する予定です。

実践でのAIナレッジの保存

AIを活用した開発では、価値ある知見が得られても、会話が終わると失われてしまうことがよくあります。MCP Commit StoryのAIナレッジ保存機能は、シンプルなワークフローでこの問題を解決します。

使用例：

1. 発見：AIアシスタントとデバッグしているときに、再レンダリングを防ぐには、計算コストの高いリスト処理にReactのuseCallbackを使うべきだと気づきます
2. 記録：journal/capture-contextツールを使って、この知見を保存します：「リスト項目の計算コストが高い処理にはuseCallbackを使う。製品カタログのレンダリング時間を60%短縮」
3. 統合：知見は適切なタイムスタンプとともに、日次ジャーナルファイルに保存されます
4. 充実：次にReactの最適化をコミットすると、ジャーナル生成システムが以前の知見をコンテキストとして自動的に含めます
5. 結果：コミットのジャーナルエントリーが以前の発見に言及し、過去の学びを積み重ねた、より充実したドキュメントが作成されます

この仕組みによって継続的な学習サイクルが生まれ、今日の知見が明日のジャーナルエントリーに活かされます。知識の喪失を防ぎ、プロジェクトで進化するパターンやソリューションへの理解を蓄積できます。

MCP Commit Storyのアーキテクチャ、ワークフロー、設計上の判断について詳しく知りたい場合は、以下を含む**技術ドキュメント**をご覧ください。

• アーキテクチャ概要 - システム設計とアーキテクチャ上の判断
• AIコンテキスト記録ガイド - ナレッジ保存の完全な使用ガイド
• MCP API仕様 - 統合のための完全なAPIリファレンス
• 実装ガイド - 開発パターンと技術的な詳細
• ジャーナルの動作 - エントリーの生成方法と構成

エンジニアリング仕様の全容については、engineering-mcp-journal-spec-final.mdをご覧ください。

---

実際のストーリー

開発者のBonnieは、数か月にわたってMCP Commit Storyを利用していました。マネージャーから過去のアーキテクチャ上の判断について尋ねられたとき、記憶を頼りにしたり、古いチケットを掘り起こしたりする必要はありませんでした。ジャーナルには、検討した代替案や判断の根拠に加え、それを裏付けるコマンドやテストまで、当時の議論が正確に記録されていました。

その後、Bonnieはジャーナルをもとにカンファレンスの講演を作成しました。技術的な手順だけでなく、道中で感じた不満や突破口、得られた教訓も見つけることができました。機能の羅列ではなく、実体験に根ざした講演だったため、多くの人の共感を呼びました。

やがてBonnieのジャーナルは、人事評価や新しいチームメイトのオンボーディング、さらには自身のキャリア形成にも役立つリソースになりました。その価値は個々のエントリーにあるのではなく、エンジニアとして歩んできた道のりを積み重ねたストーリーにありました。

実例： MCP Commit Story自体の開発は、この種のドキュメントが可能にすることを具体的に示しています。技術的な作業、感情の動き、アーキテクチャ上の発見を記録した数か月分のジャーナルエントリーは、"不安定な地盤に城を築く：誤ったAIのアドバイスに振り回された1か月"へとまとめられました。これは、当初のAI主導アーキテクチャに根本的な欠陥があると発見し、より優れたシステムへとつながった立て直しの過程を詳しく記録したものです。このブログ記事は、自動ジャーナリングによって、何を作ったかだけでなく、なぜ、どのように作ったかという全体のストーリーも記録できることを示しています。従来のドキュメントでは省かれがちな失敗や方向転換も含まれます。

---

バックグラウンド生成：今すぐ記録し、処理は静かに

MCP Commit Story は git フックを使い、コミットのたびに日誌のエントリーと日次サマリーをバックグラウンドで自動生成します。このシステムは git のコンテキストを収集し、関連する AI チャット履歴を抽出して、最近の日誌エントリーを読み込み、プロジェクトの README を含めます。これにより、プロジェクトの目的と目標を常に理解している新しい AI エージェントに包括的なコンテキストを提供します。ワークフローを中断することなく、コンテキストを踏まえた充実した日誌エントリーを生成できます。

git フックは、同期モードとバックグラウンドモードの両方をサポートします。バックグラウンドモードでは、日誌の生成を非同期で続けながら git のコミットをすぐに完了できるため、ワークフローの妨げになりません。必要に応じて手動で振り返りを追加したり、AI アシスタントの現在のコンテキストを記録したりして、完全に自分で管理できます。

---

使う理由

• 自分のために：

  • なぜ特定の選択をしたのか、また障害をどう乗り越えたのかを思い出せます。
  • コミットの一覧だけでなく、開発者としての成長を振り返れます。
  • 自分の仕事をより率直かつ明確に振り返れます。

• コンテンツ作成のために：

  • 課題や成功の軌跡を見つけ、ブログ記事、講演、ポートフォリオ作品に活用できます。
  • 技術者としての歩みのありのままのストーリーを記録できます。開発者支援、教育、あるいは未来の自分との共有に最適です。

• 振り返りとレビューのために：

  • 自分の成果、課題、意思決定の根拠をすばやく見つけられます。
  • 人事評価、キャリアアップ、チームの振り返りを、より有意義で負担の少ないものにできます。

---

プロジェクトの状況

このプロジェクトは、個人の開発者によって活発に開発されています。
中核となる日誌エンジン、コンテキスト収集、サマリー生成は、TDD を優先するアプローチで開発・テストされています。
ツールの成熟に合わせて、インストール方法と CLI の手順を追加する予定です。

---

前提条件

OpenAI API キー（AI 機能に必要）

MCP Commit Story は OpenAI の API を使って、コンテキストを踏まえた充実した日誌エントリーを生成します。AI を活用した機能を使うには、次が必要です。

1. OpenAI API キー：OpenAI Platform にアクセスして、新しい API キーを作成します
2. 環境変数の設定：

   export OPENAI_API_KEY="your-openai-api-key-here"
   

API キーがない場合：システムは引き続き動作しますが、構造形式と AI 以外のコンテンツは保持したまま、日誌エントリー内の AI 生成セクション（Summary、Technical Synopsis など）は空になります。

コスト：このシステムは、コスト効率に優れた OpenAI の gpt-4o-mini モデルを使用します。通常の利用コストはごくわずかです（開発で積極的に使っても、通常は月額 1 ドル未満です）。

---

はじめに

MCP Commit Story はまだ開発初期段階にあり、一般利用できる状態ではありません。エンジニアリングにまつわるストーリーテリング、開発者エクスペリエンスに関心がある方や、プロジェクトの進捗を追いたい方は、リポジトリをウォッチするか、意見、質問、提案を添えて issue を作成してください。プロジェクトの進展に伴い、皆さまからのフィードバックや関心を歓迎します。

---

ライセンス

MIT

---

MCP Commit Story：エンジニアリングの仕事は、コードだけではないから。

技術的な詳細

ここから始める

• アーキテクチャ概要 - システム設計、アーキテクチャ上の意思決定、コンポーネント間の関係
• エンジニアリング仕様の完全版 - 包括的なリファレンス（900 行以上）

API と統合

• MCP API 仕様 - MCP の全操作、データ形式、クライアント統合ガイド
• 実装ガイド - 開発パターン、技術的な実装、ベストプラクティス

コアシステムのドキュメント

• ジャーナルコア - ジャーナルエントリー生成システム、AI 統合、コンテンツガイドライン
• コンテキスト収集 - データ収集システム、型定義、パフォーマンス最適化
• リフレクションコア - バリデーションとテレメトリを備えた手動リフレクションの追加
• ジャーナルの動作 - エントリー構造、設定オプション、生成ワークフロー

可観測性とモニタリング

• テレメトリ - OpenTelemetry の包括的な統合とモニタリング
• 構造化ログ - トレース相関と機密データ保護に対応した JSON ロギング
• マルチエクスポーター - 環境変数の優先順位を考慮した OpenTelemetry エクスポーターの設定

開発とテスト

• テスト標準 - テスト戦略の全容（532 件のテスト、カバレッジ 80％、TDD パターン）
• サーバーのセットアップ - MCP サーバーの設定とデプロイガイド