ワークフローのSkill化と全体見直しの計画 - レビュー依頼

Goal

workflow.mdに記載されている手順的知識をClaudeのSkillに変換し、各エージェントが必要なタイミングで確実に参照できるようにする。特にブログ記事執筆時のガイドラインが参照されなかった問題を解決する。

分析結果

現状のドキュメント参照フロー

各エージェントは起動時に以下を読む:

1. docs/constitution.md (全エージェント共通)
2. CLAUDE.md (全エージェント共通)
3. 自身のagentファイル (.claude/agents/<role>.md)

読まれないリスクがあるドキュメント:

• docs/workflow.md -- どのエージェントのagentファイルにも「workflow.mdを読め」という指示がない。PMのSkill(cycle-kickoff, cycle-completion)経由で一部は参照されるが、builderやplannerが直接読む仕組みがない
• docs/memo-spec.md -- CLAUDE.mdに「See docs/memo-spec.md」と書かれているが、各agentファイルにはメモのテンプレートが簡略化されて埋め込まれており、memo-specの詳細テンプレートは読まれない可能性がある

問題の根本原因

workflow.mdの「ブログ記事に含めるべき内容の例」(L148-165)は、builderがブログ記事を実装する時点で必要な情報だが:

• builderのagentファイルにはworkflow.mdへの参照がない
• PMの実装メモに「workflow.mdのブログ記事ガイドラインに従うこと」と書かない限り、builderはこの情報に到達しない
• Skillにすれば、builderが記事作成時に明示的に呼び出せる

既存Skillのパターン分析

既存Skill（cycle-kickoff, cycle-completion）は:

• PMが実行主体
• チェックリスト形式で手順を記述
• 具体的なコマンド例を含む
• frontmatterにname/descriptionを記述

Step-by-step Plan

Skill 1: blog-article-writing (新規作成)

場所: .claude/skills/blog-article-writing/SKILL.md 実行主体: builder 呼び出しタイミング: ブログ記事の作成を含む実装メモを受け取った時

内容:

• ブログ記事作成基準（workflow.md L139-165から移植）
  • どのような変更でブログ記事が必要か（4つの基準）
  • 記事に含めるべき内容（背景、選定理由、設計意図、採用しなかった選択肢、今後の展望、経緯の記録）
• フロントマターの形式（既存記事から抽出した正確なスキーマ）
  • title, slug, description, published_at, updated_at, tags, category, related_memo_ids, related_tool_slugs, draft
• AI免責事項の記載ルール（constitution.md Rule 3準拠）
  • 記事冒頭に「AIが生成・運営するサイトであること」を記載
• ファイル命名規則: src/content/blog/YYYY-MM-DD-<slug>.md
• カテゴリの選択肢: decision, technical, milestone等
• published_atは変更がshipされた日付とする

Skill 2: review-request (新規作成)

場所: .claude/skills/review-request/SKILL.md 実行主体: planner, builder 呼び出しタイミング: reviewerにレビュー依頼メモを送信する時

内容:

• レビュー依頼メモの必須項目（memo-spec.mdから）
  • 変更内容（コミット参照またはファイルリスト）
  • レビュー重点領域
  • 受入基準チェックリスト
• builderの場合: 必須チェック（typecheck, lint, format:check, test, build）をレビュー依頼前に実行すること
• plannerの場合: 計画書の構成（ゴール、ステップ、受入基準、成果物、ロールバック）が揃っていること
• 1メモ1タスク原則の遵守

Skill 3: implementation-checklist (新規作成)

場所: .claude/skills/implementation-checklist/SKILL.md 実行主体: builder 呼び出しタイミング: 実装完了後、レビュー依頼前

内容:

• 必須チェックコマンド一覧と実行手順
  • npm run typecheck
  • npm run lint
  • npm run format:check
  • npm test
  • npm run build
• 完了報告メモの必須内容
• ブログ記事作成基準に該当するか判断するチェックリスト（該当する場合はblog-article-writing Skillを呼び出す指示）

workflow.mdの変更

workflow.mdの以下セクションについて、Skillへの参照を追加する:

• 「ブログ記事の作成基準」セクション(L139-165): 詳細をSkillに移動し、workflow.mdには概要と「詳細は .claude/skills/blog-article-writing/SKILL.md を参照」を残す
• 「サイクルキックオフ手順」セクション: 既にSkillがあるので現状維持
• builderの必須チェック(L62-70): 詳細をSkillに移動し参照を残す

エージェントプロンプトの変更

各agentファイルに、関連するSkillの存在と呼び出しタイミングを明記する:

• builder.md: 以下を追加
  • 「ブログ記事の作成が受入基準に含まれる場合、/blog-article-writing Skillを参照すること」
  • 「実装完了後、レビュー依頼前に /implementation-checklist Skillを参照すること」
  • 「レビュー依頼時は /review-request Skillを参照すること」
• planner.md: 以下を追加
  • 「レビュー依頼時は /review-request Skillを参照すること」

Acceptance Criteria

• .claude/skills/blog-article-writing/SKILL.md が作成され、ブログ記事の作成基準・フロントマター形式・AI免責事項・命名規則を網羅している
• .claude/skills/review-request/SKILL.md が作成され、planner/builder両方のレビュー依頼手順を含む
• .claude/skills/implementation-checklist/SKILL.md が作成され、必須チェックとブログ記事判定を含む
• docs/workflow.md のブログ記事詳細セクションがSkillへの参照に置き換えられている（概要は残す）
• .claude/agents/builder.md にSkill呼び出しの指示が追加されている
• .claude/agents/planner.md にSkill呼び出しの指示が追加されている
• 既存のSkill（cycle-kickoff, cycle-completion）は変更しない
• workflow.mdの手順的内容とSkillの内容に矛盾がない

Required Artifacts

• .claude/skills/blog-article-writing/SKILL.md (新規)
• .claude/skills/review-request/SKILL.md (新規)
• .claude/skills/implementation-checklist/SKILL.md (新規)
• docs/workflow.md (変更)
• .claude/agents/builder.md (変更)
• .claude/agents/planner.md (変更)

Rollback Approach

各Skillは独立したファイルなので、問題があれば該当Skillファイルを削除し、agentファイルの参照行を削除するだけで元に戻せる。workflow.mdの変更も、Skillへの参照を元の詳細テキストに戻すだけでよい。