octkp/ba2-ticket-knowledge-logger

Ticket Knowledge Logger

チケット調査・実装の会話ログとナレッジをドキュメント化するスキル。

前提

• JIRA 認証: JIRAコメント投稿（ステップ8）には Claude Code から Atlassian Rovo（mcp__claude_ai_Atlassian_Rovo__*）への接続が必要。未接続でも、ローカル記録（LOG/README/PLAN 作成）と git push までは完了し、JIRA投稿だけが失敗扱いになる。
• 実行場所: スキル実行は ba2-workspace リポ内で行うこと（git rev-parse --show-toplevel で REPO_ROOT を解決する）。

出力先ディレクトリ

ベースパスの決定（実行時に動的解決）

出力先はスキルを実施しているユーザーごとに変わる。固定パスではなく、実行時に以下の手順でユーザー名と REPO_ROOT・BASE_PATH を解決する。

ユーザー名（苗字）の解決

# whoami の出力から末尾の _◯（最後の _ 以降）を除いた苗字をフォルダ名にする
# 例: takano_y -> takano / ushiroyama_k -> ushiroyama / _ を含まない場合はそのまま
USER_NAME=$(whoami | sed 's/_[^_]*$//')
[ -z "$USER_NAME" ] && USER_NAME=$(whoami)  # フォールバック: sed の結果が空ならそのまま whoami を使う

REPO_ROOT の解決

スキルとナレッジが同じ ba2-workspace リポに同居しているため、現在の作業ディレクトリの git ルートをそのまま REPO_ROOT として使う。

REPO_ROOT=$(git rev-parse --show-toplevel 2>/dev/null)
if [ -z "$REPO_ROOT" ]; then
  echo "ERROR: ba2-workspace リポ内で実行してください" >&2
  exit 1
fi

• 環境変数や設定ファイル、対話による解決は不要（スキルとナレッジが同居しているため）。
• 万一 git 管理外で実行された場合のみエラーで止める。

BASE_PATH の確定

BASE_PATH="$REPO_ROOT/docs/$USER_NAME"

• 以降のドキュメント内で {ユーザー名} と書かれている箇所は、この USER_NAME に置き換える。
• 以降のドキュメント内で {ベースパス} と書かれている箇所は、この BASE_PATH に置き換える。

カテゴリ構造

| カテゴリ | 用途 | パス | |---------|------|------| | 調査 | バグ調査、原因特定、コード解析 | {base}/調査/BAX-XXXX_{チケット名}/ | | 実装 | 機能実装、コード変更、リファクタリング | {base}/実装/BAX-XXXX_{チケット名}/ | | その他 | その他の作業、ドキュメント作成など | {base}/その他/BAX-XXXX_{チケット名}/ |

作成されるファイル

各チケットディレクトリに以下のファイルを作成:

• LOG.md - 会話ログ（時系列の詳細記録）
• README.md - まとめ（結論・要点のサマリー）
• PLAN.md - プラン計画書（プランモード使用時に生成。タスク分解・実装方針・影響範囲などを記録）

ワークフロー

1. ユーザーからの入力を取得

ユーザーから以下の情報を受け取る:

• カテゴリ: 調査 / 実装 / その他
• チケット番号: BAX-XXXX 形式

2. JIRAからチケット名を取得

チケット番号からJIRAのチケットページにアクセスし、チケット名（Summary）を取得する。

• URL: https://kokopelli-inc.atlassian.net/browse/{チケット番号}
• WebFetchツールでページにアクセスし、チケットのタイトル（Summary）を抽出する
• 取得したチケット名はディレクトリ名に使用する（例: BAX-10325_年払い対応）
• チケット名に含まれるファイルシステムで使えない文字（/, \, :, *, ?, ", <, >, |）はアンダースコア _ に置換する
• JIRAにアクセスできない場合は、ユーザーにチケット名を直接聞く

3. ディレクトリ作成

mkdir -p "{ベースパス}/{カテゴリ}/{チケット番号}_{チケット名}"

（{ベースパス} は「出力先ディレクトリ」セクションで解決した $BASE_PATH。例: $REPO_ROOT/docs/takano/調査/BAX-XXXX_チケット名）

4. LOG.md 作成

会話ログファイルを作成:

重要: 日時は必ず YYYY-MM-DD HH:MM 形式で、時刻（HH:MM）を省略せずに記録すること。現在時刻は date "+%Y-%m-%d %H:%M" コマンドで取得できる。

# {チケット番号} 会話ログ

## 基本情報

- **チケット**: {チケット番号}
- **カテゴリ**: {カテゴリ}
- **作成日時**: {YYYY-MM-DD HH:MM}  ← 例: 2026-02-05 14:30

---

## 会話ログ

### {YYYY-MM-DD HH:MM} - セッション1  ← 例: 2026-02-05 14:30 - セッション1

#### 質問/タスク
{ユーザーからの質問やタスクの内容}

#### 調査/作業内容
{調査した内容、読んだファイル、実行したコマンドなど}

#### 結果/発見
{発見した事項、結論、解決策など}

---

### {YYYY-MM-DD HH:MM} - セッション2  ← 例: 2026-02-05 15:45 - セッション2
...

5. README.md 作成

まとめファイルを作成:

# {チケット番号}

## 概要

{チケットの目的・背景を1-2文で}

## 結論/解決策

{最終的な結論、解決策、または実装内容}

## 関連ファイル

- `path/to/file.php:123` - {説明}

## 参考情報

- {参考にしたドキュメント、URL}
- {関連するチケット番号}

## プラン

計画書は [PLAN.md](./PLAN.md) を参照。

## ログ

詳細は [LOG.md](./LOG.md) を参照。

6. PLAN.md 作成（プランモード使用時）

プランモード（EnterPlanMode）でタスクの計画を立てた場合、その計画書を PLAN.md として保存する。

タイミング: プランモードで計画を策定した直後、または記録時にプランモードの出力が会話に存在する場合。

# {チケット番号} プラン計画書

## 基本情報

- **チケット**: {チケット番号}
- **作成日時**: {YYYY-MM-DD HH:MM}
- **最終更新**: {YYYY-MM-DD HH:MM}

---

## 目的・ゴール

{チケットで達成すべきことを明確に記述}

## 現状分析

{現在のコードの状態、問題点の整理}

## 実装方針

{どのようなアプローチで解決するかの方針}

## タスク分解

- [ ] タスク1: {内容}
- [ ] タスク2: {内容}
- [ ] タスク3: {内容}

## 影響範囲

- {変更が影響するファイル・機能の一覧}

## リスク・懸念事項

- {想定されるリスクや注意点}

## 備考

{その他の補足情報}

更新ルール:

• プランモードで計画を再策定した場合は、PLAN.mdを上書き更新する（最新の計画のみ保持）
• タスク分解のチェックボックスは、実装完了時に手動またはログ記録時に更新可能
• README.mdの「関連ファイル」セクションに PLAN.md へのリンクを追加する

7. ローカルにコミット＆プッシュ（自動実行）

LOG.md / README.md / PLAN.md を作成・更新したら、ユーザーへの確認を取らずに自動でコミット＆プッシュする。これにより次のJIRAコメントで必ずGitHubリンクを付けられる。

cd "$REPO_ROOT" && \
git add "docs/{ユーザー名}/{カテゴリ}/{チケット番号}_{チケット名}/" && \
git commit -m "{チケット番号}: ナレッジ記録（{カテゴリ}）

Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>" && \
git push origin main

• 対象は当該チケットのディレクトリのみ git add する（無関係な変更を巻き込まない）。
• このリポジトリは main 直コミット運用。コミットメッセージ末尾に Co-Authored-By 行を付ける。
• 既にコミット済みで差分がない場合（nothing to commit）はスキップしてよい。
• push に失敗した場合はエラーを表示し、次のJIRAコメントは「リモート未プッシュ時のフォーマット」（GitHubリンクなし）にフォールバックする。ローカルファイルの作成は完了とみなす。

8. JIRAチケットにコメント投稿

ログやREADMEを作成・更新した際、JIRAチケットにもナレッジコメントを投稿する。

ツール

mcp__claude_ai_Atlassian_Rovo__addCommentToJiraIssue を使用する。事前に mcp__claude_ai_Atlassian_Rovo__getAccessibleAtlassianResources を 1 回呼んで cloudId（UUID 形式）を解決しておく（同一セッション内ではキャッシュしてよい）。

パラメータ

• cloudId: getAccessibleAtlassianResources で取得した UUID（kokopelli-inc.atlassian.net に対応するもの）。ドメイン文字列をそのまま渡すと API が受け付けないので注意。
• issueIdOrKey: {チケット番号}（例: BAX-10325）
• commentBody: 下記フォーマットのMarkdown文字列

GitHubリンクの確認

コメント投稿前に、LOG.mdとREADME.mdがリモートにプッシュ済みかを確認する。

確認方法:

cd "$REPO_ROOT" && \
git log --oneline origin/main -- "docs/{ユーザー名}/{カテゴリ}/{チケット番号}_{チケット名}/LOG.md" | head -1 && \
git log --oneline origin/main -- "docs/{ユーザー名}/{カテゴリ}/{チケット番号}_{チケット名}/README.md" | head -1

• 出力があればリモートにプッシュ済み → GitHubリンクをコメントに追加
• 出力が空ならまだプッシュされていない → ローカルパスのみ記載

GitHubリンクのURL形式:

https://github.com/kokopelli-inc/ba2-workspace/blob/main/docs/{ユーザー名}/{カテゴリ}/{チケット番号}_{チケット名}/README.md
https://github.com/kokopelli-inc/ba2-workspace/blob/main/docs/{ユーザー名}/{カテゴリ}/{チケット番号}_{チケット名}/LOG.md

注意: URLに日本語が含まれる場合はそのまま記載する（GitHubがURLエンコードを処理する）。

コメントフォーマット

## 📝 ナレッジ記録（{カテゴリ}）

### 概要
{チケットの目的・背景を1-2文で}

### 結論/解決策
{最終的な結論、解決策、または実装内容}

### 関連ファイル
- `path/to/file.php:123` - {説明}

### 参考情報
- {参考にしたドキュメント、URL}

### 詳細ドキュメント
<!-- リモートにプッシュ済みの場合のみこのセクションを追加 -->
- [README.md](https://github.com/kokopelli-inc/ba2-workspace/blob/main/docs/{ユーザー名}/{カテゴリ}/{チケット番号}_{チケット名}/README.md)
- [LOG.md](https://github.com/kokopelli-inc/ba2-workspace/blob/main/docs/{ユーザー名}/{カテゴリ}/{チケット番号}_{チケット名}/LOG.md)

---
*このコメントはClaude Codeのba2-ticket-knowledge-loggerスキルにより自動投稿されました*
*詳細ログ: `ba2-workspace/docs/{ユーザー名}/{カテゴリ}/{チケット番号}_{チケット名}/`*

リモート未プッシュ時のフォーマット（「詳細ドキュメント」セクションなし）:

## 📝 ナレッジ記録（{カテゴリ}）

### 概要
{チケットの目的・背景を1-2文で}

### 結論/解決策
{最終的な結論、解決策、または実装内容}

### 関連ファイル
- `path/to/file.php:123` - {説明}

### 参考情報
- {参考にしたドキュメント、URL}

---
*このコメントはClaude Codeのba2-ticket-knowledge-loggerスキルにより自動投稿されました*
*詳細ログ: `ba2-workspace/docs/{ユーザー名}/{カテゴリ}/{チケット番号}_{チケット名}/`*

注意事項

• コメントはREADME.mdの内容に基づく要約とする（LOG.mdの詳細はローカルのみ）
• 機密情報（パスワード、APIキー、内部IPアドレス等）はコメントに含めない
• コメント投稿前にユーザーに内容を確認してもらう（AskUserQuestion で「このコメントをJIRAに投稿してよいですか？」と確認。AskUserQuestion が使えない環境では通常の対話メッセージで確認する）
• コメント投稿に失敗した場合はエラーを表示するが、ローカルファイルの作成は完了とみなす

使用例

新規チケットの記録開始

ユーザー: 「BAX-10325の調査を記録して」

実行:

1. https://kokopelli-inc.atlassian.net/browse/BAX-10325 にアクセスしてチケット名を取得
2. 調査/BAX-10325_{チケット名}/ ディレクトリ作成
3. LOG.md テンプレート作成
4. README.md テンプレート作成
5. コメント内容をユーザーに確認
6. JIRAチケットにコメント投稿

ログの追記

ユーザー: 「今の会話をBAX-10325に追記して」

実行:

1. 既存のLOG.mdを読み込み
2. 新しいセッションを追記
3. README.mdを更新
4. コメント内容をユーザーに確認
5. JIRAチケットに最新のナレッジをコメント投稿

プラン計画書の保存

ユーザー: 「BAX-10325のプランを記録して」または、プランモード終了後に記録スキルを実行

実行:

1. プランモードの出力内容を取得
2. PLAN.md を作成または上書き更新
3. README.mdに「プラン」セクションのリンクを追加/更新

まとめの更新

ユーザー: 「BAX-10325のREADMEを更新して」

実行:

1. LOG.mdの内容から要点を抽出
2. README.mdを更新
3. コメント内容をユーザーに確認
4. JIRAチケットに更新されたナレッジをコメント投稿

カテゴリ判定の目安

| キーワード | カテゴリ | |-----------|---------| | 調査、バグ、原因、なぜ、エラー | 調査 | | 実装、修正、追加、変更、リファクタ | 実装 | | ドキュメント、メモ、その他 | その他 |

注意事項

• ログは時系列で追記していく（上書きしない）
• README.mdは調査/実装が完了したタイミングで更新
• 機密情報（パスワード、API キー等）は記録しない
• 日時は必ず時刻（HH:MM）まで記録すること（例: 2026-02-05 14:30、2026-02-05 だけはNG）
• LOG/README/PLAN の作成・更新後は、当該チケットのディレクトリを自動でコミット＆プッシュする（ユーザー確認不要）
• JIRAコメント投稿前に必ずユーザー確認を行う（コミット＆プッシュとは別に、投稿は要確認）
• JIRAコメントにはログの全量ではなく要約のみを投稿する