Translate To Vision Story

translate-to-vision-story

プロジェクト単位の活動を、ビジョン整合した Zenn 記事下書きに翻訳する。

何を解決するか

プロジェクトでやったこと (taimei-auth, freee-mcp, ID統合設計など) を、自分のビジョンに繋がる物語として記事化したい。しかし「何をどう書けばビジョンと整合するか」を毎回ゼロから考えるのは負担で、結果としてふりかえりが「単なる技術深掘り」で終わり、ブランディングに繋がらない。

このスキルは、~/.claude/skills-config/vision.md に書かれたビジョン要素と照合しながら、5 ステップの対話フローで Zenn 記事下書きを生成する。

入出力

• 入力: プロジェクトディレクトリのパス (例: ~/mydev/taimei)
• 出力: Zenn 記事下書き Markdown ファイル (デフォルト: /docs/draft/YYYY-MM-DD-.md)

前提

• ~/.claude/skills-config/vision.md が存在すること
• 存在しない場合は references/vision-config-template.md をコピーして編集を促す

5 ステップ対話フロー

Step 1: 文脈把握

入力受け取り

ユーザーが /translate-to-vision-story または「物語化したい」と発話したら起動する。`` を引数または対話で受け取る。

必須読み込み

各ステップは「成功 / 空・件数不足 / 欠落」の 3 分岐を明示する。skip した情報源は肝推定時に「○○ 由来情報なし」と内部メモする (後続 Step で証拠の偏りを判断するため)。

1. ~/.claude/skills-config/vision.md を Read

• 成功 → ビジョン要素 (V1-V10) を把握
• 不在 → エラーハンドリング表 1 行目に従う (skill を一旦中断)

1. /README.md を Read

• 成功 → 肝推定の主要証拠として使用
• 不在 → skip (内部メモ: README 由来情報なし)

1. ` で git log --oneline -50` を実行し直近コミットを取得

• 50 件以上 → そのまま使う
• 50 件未満 → 全件を使う (リポが小さくても abort しない)
• git history 自体が無い → エラーハンドリング表 2 行目に従う

1. ` で gh pr list --state merged --limit 30 --json number,title,mergedAt` を実行 (gh 利用可能時のみ)

• 利用するフィールド: number (関連活動表記用), title (柱抽出用), mergedAt (時系列把握用)
• gh 利用不可 → skip (内部メモ: PR 由来情報なし)
• 0 件 → skip (内部メモ: PR 駆動開発でない)

1. ADR ファイルを以下 3 パターンの Glob で探索 (これ以外には掘らない: 親ディレクトリの再帰探索は対象外)

• /docs/adr/*.md
• /adr/*.md
• /../docs/adr/*.md
• 1 件以上見つかった → 各ファイルを Read し肝推定の重み付け証拠に使う (代替案・却下理由が書かれている率が高いため)
• 全パターン 0 件 → skip (内部メモ: ADR 由来情報なし)

「肝 3 点」初期提案

収集した情報から、AI が「このプロジェクトの肝はこの 3 点」を初期提案する。

ビジョン要素紐付けの優先順位:

• Tier 1 (V1-V7 などの確定要素) を優先採用、Tier 2 (V8-V10 などの候補要素) は Tier 1 で説明できない場合の補完として使う
• 1 柱あたり 1-3 個の要素を紐付ける (4 個以上は柱として広すぎるサインなので柱を分割するか粒度を揃える)
• vision.md 内に Tier 区分が無い場合は ID 順に上位優先

整合点の分岐:

• 全柱で整合要素ゼロ → 初期提案フォーマットを送らずエラーハンドリング表「ビジョン整合点ゼロ」行に分岐
• 一部の柱のみ整合要素ゼロ (他柱は整合あり) → 通常フォーマットで提示し、Step 2 の確定後処理で「失敗談として扱う」マーク付け

形式:

このプロジェクトの肝は以下の 3 点と推定しました:

1. **(技術的判断 1)** — (1-2 行の説明)
   - 関連活動: (commit hash / PR# / ADR-N 等)
   - 推定整合ビジョン要素: V_x

2. **(技術的判断 2)** — ...
3. **(技術的判断 3)** — ...

この 3 点で物語化を進めて良いですか? 違うなら指摘してください。

→ Step 2 (柱確認) へ。

Step 2: 物語の柱の確認 (=最重要)

ユーザー応答パターン

| ユーザー応答 | 動作 | |---|---| | 「OK」「いいよ」「進めて」 | 3 点を確定し Step 3 へ | | 「(別の柱を提示)」 | 提示された柱で再構成、再度ユーザー確認 | | 「○番を変えたい」 | 該当番号のみ AI が再生成、再度ユーザー確認 | | 「3 点じゃなくて 2 点でいい」 | 数を調整して再構成、再度ユーザー確認 |

柱の合意なしに Step 3 (下書き生成) に進んではならない。 誤った柱で進むと revise loop が無限化する。

確定後の処理

確定した柱ごとに、vision.md のビジョン要素 (V1-V7 等) と紐付ける。整合する要素が複数ある場合は全て列挙する。整合する要素がゼロの柱は「ビジョンに整合しない柱」としてマークし、Step 3 で「失敗した点 / ビジョンに整合しなかった点」セクションに含めることを提案する。

確定結果のフォーマット:

柱が確定しました:

1. (柱 1) → V1, V4
2. (柱 2) → V5
3. (柱 3) → 整合要素なし (失敗談として扱う)

下書きを生成します...

→ Step 3 へ。

Step 3: 下書き生成

出力先パスの決定

デフォルト: /docs/draft/YYYY-MM-DD-.md

• `` は柱から自動生成 (例: 「taimei-auth-separation」「freee-mcp-namespace-pattern」)
• ファイル名候補をユーザーに提示し、変更を許可
• /docs/draft/ ディレクトリが存在しなければ作成する

下書きの 3 段構成

${CLAUDE_PLUGIN_ROOT}/skills/translate-to-vision-story/references/zenn-article-structure.md の構造に従う:

1. 背景 (200-400 字) — なぜこのプロジェクトを始めたか / 解決したい課題 / ビジョン要素との繋がりを 1 文
2. 取り組み (1500-3000 字) — 技術詳細 / 重要な設計判断 (検討した代替案と却下理由) / コード例
3. ビジョンへの繋がり (200-400 字) — どのビジョン要素を前進させたか / 次の手

「ビジョンに整合しなかった柱」がある場合は、3. の前に「失敗した点 / ビジョンに整合しなかった点」セクションを追加する。

Frontmatter

---
title: "(自動生成)"
emoji: "💭"
type: "tech"
topics: ["claudecode"]  # 柱から推定して追加
published: false
---

ファイル書き出し

Write ツールでファイル作成。書き出し後、ユーザーに以下を提示:

下書きを生成しました: 

変更したい箇所があれば教えてください:
- 「ここ弱い」「ここ強調」「この技術詳細追加」「カット」 などの FB を受け付けます
- 「OK」と言えば完了処理に進みます

→ Step 4 へ。

Step 4: revise loop

ユーザー FB の解釈

| FB パターン | 動作 | |---|---| | 「○○を強調」 | 該当箇所を 50% 程度厚くする (Edit でファイル更新) | | 「○○弱い / 詳細追加」 | 該当箇所に技術詳細・コード例・図を追加 | | 「○○カット」 | 該当箇所を削除、前後を接続 | | 「○○を別の言い方で」 | 該当箇所を書き換え | | 「ビジョン要素 V_x への繋がりが弱い」 | 該当ビジョン要素について追記 | | 「OK」「これで完了」 | Step 5 へ |

revise の単位

• 1 FB につき 1 ファイル更新 (Edit) で対応
• 大規模な書き換えが必要な場合は Write で全文書き直し
• 各 revise の後、変更要約をユーザーに提示してから次の FB を待つ

revision-log の記録

Step 5 で revision-log を記録するため、各 revise の内容を内部的に保持する。形式:

- (revise 1) ユーザー FB: "○○強調" → 該当段落を厚くした
- (revise 2) ユーザー FB: "V_x への繋がり弱い" → 該当ビジョン要素について追記
- ...

loop 終了

ユーザーが「OK」「これで完了」「いいよ」と発話したら Step 5 へ進む。

→ Step 5 へ。

Step 5: 完了処理

最終版保存

最終版をそのまま保存 (revise loop の最後の Edit / Write 結果が最終版)。

revision-log のコメント挿入

ファイル末尾に HTML コメント形式で revision-log を埋め込む (Zenn 記事として publish 時には表示されない、再 revise 時の参考資料)。

ビジョン要素タグ付与 (オプション)

ユーザーが希望すれば、各 H2 段落の冒頭に整合するビジョン要素を HTML コメントで付与する:

## 取り組み

(段落本文)

完了メッセージ

記事下書きが完成しました: 

次にやること:
1. このファイルを Zenn ローカル CLI で preview する
2. 必要に応じて手動で文章を磨く
3. publish 準備が整ったら frontmatter の `published: true` に変更

skill 終了。

エラーハンドリング

| 状況 | 動作 | |---|---| | ~/.claude/skills-config/vision.md が存在しない | エラーメッセージ最低含有要素 (1) に従いユーザー提示。承認後コピー → 編集 → skill 再実行 | | `` に git history が無い | エラーメッセージ最低含有要素 (2) に従いユーザー提示 | | ビジョン整合点ゼロ (全柱で整合要素ゼロのとき) | エラーメッセージ最低含有要素 (3) に従いユーザー提示 | | 出力先ディレクトリが書き込み不可 | 別パスを提案、または abort |

エラーメッセージ最低含有要素

各エラー提示メッセージに以下を必ず含める。要素の欠落は不可。

• 提示順序: 下記の箇条書き順を推奨 (executor が UX 上必要なら入れ替え可)
• 文言: 意味が同等なら自由に言い換え可 (鍵括弧表記は固定文言ではなく例示)
• Markdown 装飾 (見出し / 太字 / リスト): executor 裁量
• 変数表記 (${CLAUDE_PLUGIN_ROOT} 等): ユーザー提示メッセージ内ではそのまま展開せず変数表記のままで可

(1) vision.md 不在時

• 検知結果: ~/.claude/skills-config/vision.md が存在しない旨を明示
• 必須理由 1 文: 「ビジョン要素とプロジェクト活動を照合するため設定ファイルが必須」
• コピー元パス: ${CLAUDE_PLUGIN_ROOT}/skills/translate-to-vision-story/references/vision-config-template.md
• コピー先パス: ~/.claude/skills-config/vision.md
• 承認待ちで停止する旨 (承認なしにコピーしない)
• 承認後の 3 段手順:

1. AI がテンプレートをコピー
2. ユーザーがテンプレート内「ビジョン要素 (判定基準)」セクションの V1-V7 等を自分の言葉で記入 (Tier 区分があれば Tier 1 を最優先で埋める)
3. ユーザーが /translate-to-vision-story を再実行

• 拒否選択肢の明示 (「やめる」「中断」等で skill 終了)

(2) git history 不在時

• 検知結果: `` に git history が無い旨
• 代替案 1: README.md とディレクトリ構造から推定して進める
• 代替案 2: abort
• ユーザー選択待ちで停止する旨

(3) ビジョン整合点ゼロ時

• 検知結果: 抽出した柱と vision.md の要素が 1 つも整合しなかった旨
• 解釈の提示: 「ビジョンに整合しない理由自体が記事ネタになる場合もある」
• 選択肢:
• 続行 (「失敗した点 / ビジョンに整合しなかった点」セクション中心の記事として下書き生成)
• abort
• ユーザー選択待ちで停止する旨

既存 skill との関係

• define-acceptance-criteria / mece-plan-review / finalize-plan 等の「プラン駆動開発」スキル群とは別レイヤー (career 系)
• 既存スキルがプロジェクト内部のフェーズを扱うのに対し、本スキルはプロジェクト全体を入力に取りキャリアレイヤーで物語化する

関連 ADR / spec

• spec: ~/.claude/plans/translate-to-vision-story.md
• ADR-003 (要修正): session-handoff の代替として本スキルを優先実装

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: YasuakiOmokawa
• Source: YasuakiOmokawa/skills
• License: MIT

Install and usage instructions live in the source repository linked above.