implementation-log

name	implementation-log
description	コード変更を伴う作業（バグ修正・機能追加・リファクタ）を完了した直後に、作業内容を新規 Markdown ファイルとして docs/ 配下に残すためのスキル。ユーザーが明示的に `/implementation-log` を呼んだ場合だけでなく、作業が一段落して「終わった」「できた」「完了」と判断できるタイミングでも自動的に提案する。デバッグ調査の過程・根本原因・採った対処・検証方法をあとから辿れる形で残したいときは必ずこのスキルを使うこと。過去に同様の不具合が再発したときに、ソースの `path:line` を根拠として当時の判断を再確認できることが目的。

implementation-log

このスキルの目的

コード変更を伴う作業を完了した直後に、作業内容を 1 本の Markdown ファイルとして docs/ に残す。後日同じ問題に戻ってきたときや他の開発者が経緯を追いたいときに、コミットメッセージや diff だけでは拾えない「なぜ／どこで／どう判断したか」を即座に思い出せるようにすることが目的。

いつ動くか

自動的に提案する

• バグ修正を完了したとき
• 新機能を実装完了したとき
• リファクタ・移行作業を完了したとき
• 非自明な調査の末に結論や対処を出したとき（たとえ最終的にコード変更が無くても、判明した事実を残す価値がある）

作業完了の報告をしたら「docs/ に実装ログを残しますか？」と確認してから書くこと。勝手に書き始めない。

明示呼び出し

ユーザーが /implementation-log と打ったときは、直前の作業内容をもとに即座に書く。

書き出すファイル

配置先

• ファイルはプロジェクトルート直下の docs/ に置く。
• docs/ が存在しなければ git rev-parse --show-toplevel で git ルートを特定した上で作成する。
• git リポジトリの外で実行された場合はユーザーに配置先を確認する（勝手にホームや親ディレクトリに作らない）。

ファイル名

• kebab-case の英字で、作業内容を端的に表す名前にする。
• 日付・タイムスタンプは付けない。内容で識別する。
• 既存ファイル名と衝突したら -2, -3 などの suffix を付ける（先頭側ではなく末尾）。

良い例:

• terminal-render-reliability.md
• auth-middleware-rewrite.md
• ingest-pipeline-retry.md

悪い例:

• 2026-04-18-fix.md（日付が入っている）
• fix.md（内容が分からない）
• FixTerminalRenderBug.md（kebab-case でない）

既存ファイルには追記しない

これは重要な原則。似たテーマの古いログがあっても必ず新規ファイルを作る。理由は次の 2 つ:

1. 時系列のスナップショットとして「そのとき何が分かっていたか」を固定したいから。追記すると過去の判断が現在の理解で書き換わってしまう。
2. Markdown のレンダリングが破綻しやすいから（見出し階層の衝突、目次の崩れ）。

旧ファイルと内容がリンクする場合は「参照」セクションで相互リンクを貼る。

ファイル内容テンプレート

次のテンプレートに必ず従う。セクション順序も固定。

# {タイトル}

## 症状 / 背景
何が問題だったか、なぜ作業したか。事実ベースで簡潔に。
再現条件や観測された現象を、推測と切り分けて書く。

## 根本原因
調査で判明した原因。複数あれば番号付きの箇条書き。
ソース参照は `path:line` 形式で必ず残す（例: `ghostty/src/renderer/Metal.zig:114-126`）。
推測混じりの場合は「確定」「高確度」「仮説」のいずれかを明示する。

## 対処
変更したファイルごとに、何をどう変えたか。
副作用や意図的に変えなかった箇所（やらなかった理由）にも言及する。
コード断片は triple backtick fenced block で。

## デバッグ / 検証方法
再現手順・環境変数・確認コマンド・テストケース。
将来の再発時に「まずこれを試せ」と示せるレベルの具体性で書く。

## 参照
参照した外部・内部コードのパスやリンク。
関連する過去の実装ログがあればそれも相互リンクする。

スタイル

• 日本語で書く。 コード識別子・ファイルパス・コマンド名は原文のまま（英数字）。
• 事実ベース。 「〜と思われる」「〜のような気がする」は避ける。分からないなら「未確定」「仮説」と明示する。
• 冗長な前置きを書かない。 「この度は……」「今回の作業では……」のような導入は省く。いきなり症状から始める。
• 意思決定の根拠を残す。 なぜその対処を選んだか／なぜ他の選択肢を選ばなかったかを、判断の痕跡として書く。
• コードは fenced block。 インラインでパスを書くときはバッククォート囲み。
• 絵文字は使わない。 見やすさを装飾に頼らず、見出しと段落で構造化する。
• 実装していない内容を「実装した」と書かない。 プランに留まった場合は「対処」セクションではなく「検討した対処（未実施）」として書く。

後処理

ドキュメントファイルを追加したら、プロジェクトの CI コマンドを実行する。プロジェクトごとにコマンドが違うので、次の順で確認する。

1. プロジェクトルートの .claude/rules/ci.md に記載があればそれを優先する。
2. CLAUDE.md にコマンドが書かれていれば従う。
3. どちらも無ければ、言語・ツールチェーンから推定する:
   • Go プロジェクト: go fmt ./... && go vet ./... && go test ./...
   • Node.js: npm run lint && npm test（package.json の scripts を見る）
   • Python: ruff check && pytest（設定ファイルに応じて調整）

Markdown 単体の追加でも fmt/vet 相当は通して、他のコード変更が巻き込まれてエラーにならないか確認すること。

典型的なやりとり

例 1: バグ修正完了直後

ユーザー: OK、これで毎回描画されるようになった、コミットしよう
アシスタント: docs/ に実装ログを残しますか？ 次のような構成で書けます:
  - タイトル案: terminal-render-reliability.md
  - 症状: 4 回に 1 回しか描画されない
  - 根本原因: layer-hosting 設定順序違反 / 非メインスレッド呼び出し
  - 対処: setWantsLayer 削除 + ebiten.RunOnMainThread 化
ユーザー: お願い
アシスタント: [ファイル作成 → CI 実行]

例 2: 明示呼び出し

ユーザー: /implementation-log
アシスタント: [直前の作業内容をサマライズして docs/<name>.md を新規作成]

例 3: 書かなくていい場合

ユーザー: README の typo を直した
アシスタント: このレベルなら diff とコミットメッセージで十分だと思います。ログは省略しますか？

判断基準: 「半年後に自分（または他の開発者）が同じ現象に出会ったとき、diff を読むだけで復元できる内容ならログ不要。そうでなければ書く。」

やらないこと

• utils フォルダ／ファイルを新たに作る（プロジェクト規約で禁止されていることが多い）。
• 既存 .md への追記。
• 実装前の計画を「実装ログ」と称して置く（/Users/yuuki/.claude/plans/ などに計画は別途ある）。
• ユーザーに確認せず勝手にコミットする。ログ追加も必ず確認を取ってから。