git-journal

Git Journal

コード変更の「なぜ」を記録します。Git が記録するのは、何を／どこで／いつ／誰が変更したかです。このスキルでは、なぜ変更したのかを記録します。

このスキルの出力は2種類です。

出力	保存場所	目的
技術ジャーナル	journals/YYYY-MM-DD_<branch>.md	ブランチ単位の変更ログ：トレードオフ、代替案、技術的な詳細
ビジネス文書	docs/	機能領域ごとに、現在の状態を継続的に記録する QA ドキュメント

git-journal を実行するたびに、技術ジャーナルのフローを変更せずに実行した後、ビジネス文書の更新が必要かどうかを評価します。

トリガーフレーズ

フレーズ	動作
「journal を忘れずに」	セッション中ずっとリマインダーを有効にします。重要な決定の後にジャーナルへの記録を積極的に検討し、ビジネス文書も評価します。
「ジャーナルに記録することはある？」	セッションを振り返り、ジャーナルの項目と必要な文書更新を提案します。
「これをジャーナルに記録して」	現在の状況をジャーナルに記録し、ビジネス文書への影響を評価します。
「ジャーナルを更新して」	ジャーナルスクリプトを実行し、「なぜ」の内容を尋ねます。
「ドキュメントを更新して」	ドキュメントスクリプトを実行し、ビジネス上の背景を尋ね、関連する docs/ ファイルを更新します。
「ドキュメントに記録することはある？」	現在の作業に関して、ビジネス文書の作成や更新が必要かどうかを確認します。

「journal を忘れずに」モード

有効にすると、セッション全体を通してジャーナルへの記録を意識します。

• 複雑な問題を解決した後 → 推論の記録を検討する
• アーキテクチャ上の決定の後 → トレードオフを記録する
• 却下したアプローチの後 → 却下した理由を記録する
• コミットの前 → 未記録の状況があれば確認する
• ユーザー向けの動作を変更した後 → docs/ の更新を評価する

「ジャーナルに記録することはある？」の振り返り

尋ねられたら、次の項目を確認します。

1. 現在のブランチにおける最近の git コミット
2. この会話中に行ったコード変更
3. 話し合った決定とトレードオフ
4. 実装した、分かりにくい解決策や回避策

そのうえで、ジャーナルに記録する具体的な項目を提案し、ビジネス文書を評価するか、記録すべき重要な内容がないことを確認します。

---

Part 1: 技術ジャーナル（変更なし）

クイックスタート

1. ジャーナルが存在することを確認します。

   python skills/git-journal/scripts/ensure_git_journal.py
   

2. 現在の状態で更新します。

   python skills/git-journal/scripts/update_git_journal.py
   

3. Why セクションを記入します（Who／When／What は自動処理されます）。

ジャーナルの保存場所

journals/YYYY-MM-DD_<branch-name>.md

• ブランチごとにジャーナルを1つ作成します
• フラットなファイル構成にします（入れ子のフォルダーは作成しません）
• ブランチ名は正規化されます（スラッシュ → ハイフン）

5 W の優先順位

1. Why ← 最優先。必ず記録します。
2. What — 概念的な要約
3. Where — 影響を受ける主要な領域
4. Who — git config から取得
5. When — タイムスタンプ

時間が限られている場合、正確でなければならないのは Why だけです。

Why に記載する内容

## Why, current summary

**Intent**
- Refactored auth to support background token refresh

**Constraints**
- Must work offline after initial auth

**Tradeoffs**
- Added complexity for better UX

**Alternatives considered**
- Redux approach: rejected due to complexity

**Non-obvious nuance**
- Retry loop looks like a bug but handles edge case where...

以下を含めます。

• 解決する問題
• この解決策を選んだ理由
• 制約（時間、プラットフォーム、API、ビジネス）
• 却下した代替案と、その理由
• 間違っているように見えても正しいこと

ジャーナルの構成

2つの階層があります。

• 上部：集約された要約（定期的に統合）
• 下部：詳細なログ（タイムスタンプ付きの追記専用エントリー）

---

Part 2: ビジネス QA ドキュメント

目的

docs/ は、ビジネスの観点から見たプロダクトの現在の状態を記録するものであり、変更ログではありません。ジャーナルには技術的な推論を段階的に記録し、ドキュメントには機能領域ごとに内容を集約します。これにより、QA、AI エージェント、将来的な Notion 同期で、どのように動作すべきか、そしてその理由は何かを確認できます。

ドキュメントの保存場所

docs/
  _index.md                 # Master entry: taxonomy, app matrix
  <domain>/
    _index.md               # Domain overview, sub-feature links
    <feature>.md            # Feature detail (when enough content warrants a file)

分類ルール：

• ブランチや技術レイヤーではなく、ビジネス領域（auth、shop、arena）ごとに整理します
• ブランチやパッケージのヒントを対応付けます：feat-auth → auth/、feat-shop → shop/ など
• 新しいビジネス領域に関わる作業では、新しい領域フォルダーを作成します
• 個別に扱う詳細がある場合にのみ <feature>.md に分割し、それ以外は領域の _index.md にまとめます
• フォルダー名は小文字とハイフンを使用します（例：attend2earn、watch2earn）

Apps と applies_to

どのアプリに適用されるかを必ず確認してください。有効な値は次のとおりです。

値	意味
wunderfan	Wunderfan のみ
wunderpar	Wunderpar のみ
golf-champs	Golf Champs のみ
wunderfan, wunderpar	共通（両方）
all	すべてのアプリ

YAML フロントマターには applies_to: [wunderfan, wunderpar] を使用します。アプリごとの差異は ## App-Specific Behavior の下に ### Wunderfan、### Wunderpar などとして記述してください。ドキュメント全体を重複させないでください。

Feature File Format

新しい機能ファイルには assets/docs-feature-template.md を使用します。必須のフロントマター：

---
domain: auth
feature: sign-in
applies_to: [wunderfan, wunderpar]
last_updated: YYYY-MM-DD
---

セクション（実装ではなく意図を記述）：

• Business Intent — 解決する問題、機能が存在する理由
• User Experience — ハッピーパスを平易な言葉で説明
• Business Rules — 適用されるルール
• Acceptance Criteria — Given／When／Then、またはテスト可能なチェックリスト
• App-Specific Behavior — アプリごとの差異
• Edge Cases — 失敗時の経路、境界条件
• Open Questions — 未解決の項目。回答済みの場合は [Resolved YYYY-MM-DD] を付ける

内容を変更するたびに last_updated を更新してください。ドキュメント内でジャーナルに言及しないでください。ジャーナルは変更履歴であり、ドキュメントは現在の状態を記述するものです。

Business Docs Quick Start

1. ドキュメントの骨組みが存在することを確認します：

   python skills/git-journal/scripts/ensure_docs.py
   

2. 分類体系を確認します（エージェントのコンテキスト用）：

   python skills/git-journal/scripts/update_docs.py --list
   

3. ドメイン／機能ファイルを作成または更新します（エージェントが内容を記述し、スクリプトで骨組みを作成できます）：

   python skills/git-journal/scripts/update_docs.py --domain auth --feature sign-in
   

Enhanced Flow (every journal invocation)

1. Technical journal     → ensure + update + write Why (existing flow)
2. Analyze changes       → user-facing vs purely technical?
3. Map taxonomy          → which domain(s)? new domain?
4. Load existing docs    → ensure_docs.py if needed
5. Assess impact         → business change? if no, skip docs
6. Prompt user           → question framework (below); never guess
7. Update docs           → merge into current-state files; set last_updated
8. Staleness check       → flag docs that may contradict current work
9. Update root _index.md → taxonomy + app matrix from frontmatter

技術的な変更のみ（リファクタリング、依存関係の更新、UX の変更を伴わない内部名称の変更）→ ジャーナルのみを更新し、古くなっている懸念がない限りドキュメントの更新は省略します。

Question Framework

必要なことだけを尋ねてください。毎回すべての項目について質問する必要はありません。

必ず確認すること（すでに判明している場合を除く）：

• どのアプリに適用されますか？（Wunderfan／Wunderpar／Golf Champs／すべて）

新機能または新しいドメインの場合：

• ユーザーにとって、どのようなビジネス上の問題を解決しますか？
• ユーザー体験はどのようなものですか？（ハッピーパス）
• この動作にはどのようなビジネスルールが適用されますか？
• ユーザーの視点から見た成功とはどのような状態ですか？

既存機能の更新の場合：

• この変更はユーザー向けの動作に影響しますか。それとも技術的な変更のみですか？
• 既存のビジネスルールに影響しますか？
• 適用対象のアプリに変更はありましたか？

古くなっている可能性がある場合：

• [domain] のドキュメントには [behavior X] と記載されています。現在の作業で変更されましたか。それとも、まだ正確ですか？

コンテキストが不明確な場合：

• [edge case] が発生したとき、具体的に何が起こりますか？
• [assumption from existing docs] は、現在も有効ですか？

ユーザーが回答できない場合は、ビジネスルールを推測せず、ドキュメントに未解決の質問として記録してください。

Root _index.md

次の項目を維持します：

• 分類体系 — _index.md または機能ファイルへのリンクを含むドメインの表
• アプリマトリックス — フロントマターから導出した、各ドメイン／機能が適用されるアプリ
• 最終更新日 — インデックスを再生成した日付

ドキュメントの変更後、フラグを付けずに update_docs.py を実行してインデックスを更新します。

---

Integration

すぐに使える Cursor ルールについては、references/cursor-rule-template.md を参照してください。

任意の pre-commit フック：

#!/bin/sh
python skills/git-journal/scripts/ensure_git_journal.py
python skills/git-journal/scripts/ensure_docs.py

Files

ジャーナル（変更なし）：

• scripts/ensure_git_journal.py — ジャーナルがない場合に作成
• scripts/update_git_journal.py — Who／When／What を更新
• assets/git-journal-template.md — 新しいジャーナル用テンプレート

ビジネスドキュメント：

• scripts/ensure_docs.py — docs/ とルートの _index.md がない場合に作成
• scripts/update_docs.py — 分類体系の一覧表示、ドメイン／機能の骨組み作成、インデックスの更新
• assets/docs-index-template.md — ルート docs/_index.md のテンプレート
• assets/docs-domain-template.md — ドメイン docs/<domain>/_index.md のテンプレート
• assets/docs-feature-template.md — 機能ファイルのテンプレート

共通：

• references/cursor-rule-template.md — Cursor ルールのテンプレート