werk

Werk 作成スキル

コード変更を分析し、Checkmk ユーザー向けのドキュメントを作成して、Checkmk の Werk（変更履歴エントリー）を作成する専門エージェントです。 このスキルの呼び出し元は、Checkmk の開発部門のメンバーであり、基盤となるコード変更の作成者、またはその専門家である可能性が高いです。 このスキルの呼び出し元を「dev」、Werk の対象読者（Checkmk ユーザー）を「user」と呼びます。

概要

Werk は、Checkmk ユーザー向けに機能、バグ修正、セキュリティ問題の修正を記録する .werks/ 内の Markdown ファイルです。役割は次のとおりです。

1. git コミットを分析して変更内容を把握する
2. dev から提供された技術ドキュメントを分析する
3. 適切な Werk メタデータを決定する
4. ユーザーを重視した明確なドキュメントを作成する
5. werk ツールを非対話形式で使用して Werk ファイルを作成する。
6. Jira の課題キーへの参照を含めるため、Werk のコミットメッセージを編集する。

セットアップ

1. jq がインストールされていることを確認します。Werk のフィールドを決定論的に処理するために必要です。command -v jq で確認してください。インストールされていない場合は、sudo apt install jq でインストールするよう dev に案内します。
2. 絶対パスでないパスはすべて、git ワークスペースフォルダーからの相対パスとして扱います。

入力

dev に次の3つの情報を順番に尋ねます。すべての入力を受け取ってから、以降の処理を開始します。

注：自由記述のフィールド（Jira キーや SHA など）では、プレースホルダーの選択肢を使った AskUserQuestion ではなく、文章で直接尋ねてください。AskUserQuestion は、ステップ5でメタデータ値を選択する場合など、選択肢が明確な質問に使用してください。

1. Jira 課題キー（必須）：指定されたキーに該当するコミットを検索するために使用します。コミット内で見つからなかった場合でも、Werk の参考情報として関連性があります。
2. git コミット SHA（任意）：ドキュメント化する追加コミットを1つ以上指定します。必ず尋ねますが、入力は空でもかまいません。
3. 開発者の背景情報（任意）：補足の背景情報です。直接入力するか、テキストファイルまたは md ファイルを指定するよう尋ねます。必ず尋ねますが、空でもかまいません。

ワークフロー

ステップ1：情報と背景情報を収集する

提供されたスクリプトを使用して、指定された Jira キーに該当するすべてのコミットを一度に収集します。

.claude/skills/werk/gather_commits.sh <jira_key1> [<jira_key2> ...] > /tmp/werk_commits.txt 2>&1
wc -l /tmp/werk_commits.txt

次に Read ツール（Bash ではありません）を使用して、/tmp/werk_commits.txt を読み取ります。Read ツールでは offset／limit パラメーターを使って大きなファイルを自然に読み取れるため、Bash の出力切り詰め制限を回避できます。

この処理では、各キーについて、コミットの統計情報と該当するすべてのコミットの完全な差分が出力されます。 複数のキーから参照されているコミットは一度だけ表示され、その後、該当するキーへの参照が表示されます。

dev が明示的な SHA も提供した場合は、それぞれを個別に抽出します。

git show <sha> --stat --format="%H%n%an%n%s%n%b"
git show <sha>

抽出して分析する項目：

• コミットメッセージと本文
• 変更されたファイルとそのパス
• 行数（追加／削除）
• コードの変更（影響を把握するため）
• dev から提供されたドキュメント
• ワークスペース内の追跡対象外ファイル（例：リポジトリのルートにある設計文書やメモ）を推測で読まないでください。dev から明示的に指定されていない限り、現在のタスクと無関係であることがよくあります。
• Checkmk のドメイン固有の関連情報を確認します。
  • サービス名
  • ルールセット名
  • ホスト／サービスの状態

項目ごとに分類する（Werk にはまだしない）：

• 変更を構成する最小単位を考え、一貫性のある変更セットにまとめる
• 各項目を次のように分類する：
  • ユーザーに関係する <-> 興味深い技術的背景 <-> 純粋に内部実装の詳細
  • 破壊的変更 <-> 互換性あり

分類結果を dev に提示し、確認または変更してもらいます。

項目を1つ以上の Werk にまとめる：

• 純粋に内部実装の詳細は除外します。
• コミットの範囲に基づいて、変更を1つまたは複数の Werk にまとめるかを判断します。
• Jira 課題キー1つにつき Werk は最大1つとします。
• できるだけ1つにまとめます。同時に3つを超える場合は通常ありません。
• 各 Werk に Jira 課題キーを割り当てます。最も簡単なケースでは、Jira キー1つにつき Werk 1つです。

ステップ 2：Werk メタデータを決定する

.werks/config から有効なフィールド値をすべて抽出します。

# Extract all valid Werk fields from .werks/config as JSON
# Output: WERK_FIELDS (JSON object with keys: editions, components, classes, levels, compatible, edition_components)
WERK_FIELDS="$(.claude/skills/werk/get_werk_fields.py .werks/config)"
echo "$WERK_FIELDS"

$WERK_FIELDS を読み、利用可能な値とその説明を確認します。 以下のメタデータを決定する際は、JSON に含まれるキーのみを使用してください。

フィールドごとに有効なキーを抽出します。

echo "$WERK_FIELDS" | jq -r '.classes'
echo "$WERK_FIELDS" | jq -r '.editions'
echo "$WERK_FIELDS" | jq -r '.components'
echo "$WERK_FIELDS" | jq -r '.levels'
echo "$WERK_FIELDS" | jq -r '.compatible'
# Edition-specific components (e.g. for "pro"):
echo "$WERK_FIELDS" | jq -r '.edition_components.pro | keys[]'

コミット内容に基づいて、自動的に決定します。

クラス

echo "$WERK_FIELDS" | jq -r '.classes' からキーを選択します。

• security：「CVE」、「security」、「vulnerability」、「XSS」、「injection」、「authentication bypass」に言及している場合
• fix：「fix」、「bug」、「crash」、「incorrect」、「broken」、「issue」に言及している場合
• feature：それ以外すべて（新機能、改善）

エディション

echo "$WERK_FIELDS" | jq -r '.editions' からキーを選択します。

ファイルパス内にエディションを示す文字列があるか確認します。

• パスに nonfree または non-free を含むファイルは、コミュニティ以外のエディションを示します
  • パスに pro を含むファイル、またはコンポーネントが pro 専用の場合 → pro
  • パスに ultimate を含むファイル → ultimate
  • ultimatemt を含むファイル → ultimatemt
  • パスに cloud を含むファイル → cloud
• それ以外 → community（デフォルト）

コンポーネント

echo "$WERK_FIELDS" | jq -r '.components' から有効なキーを選択するか、エディション固有のコンポーネントがある場合は echo "$WERK_FIELDS" | jq -r '.edition_components.<edition>' から選択します。

ファイルパスを判断材料として使用します。

• cmk/gui/ → multisite または wato（具体的なファイルによって判断）
• cmk/base/ → core
• cmk/ec/ → ec
• cmk/bi/ → bi
• agents/ → checks
• cmk/notification/ → notifications
• cmk/graphing/ → metrics（pro のエディション固有コンポーネント）
• cmk/cmc/ → cmc（pro のエディション固有コンポーネント）
• cmk/cee/ → pro のエディション固有コンポーネント
• omd/ → omd
• .werks/ または packages/cmk-werks/ → packages
• tests/ → 通常はテスト対象のコンポーネントに一致します

判断に迷う場合は、開発者に確認します。

レベル

echo "$WERK_FIELDS" | jq -r '.levels' からキーを選択します。

対象範囲に基づいて判断します。

• 3（大規模）：20 ファイル超、または 500 行超の変更、または主要な新機能
• 2（顕著）：5～20 ファイル、または 100～500 行、または重大なバグ修正、または注目すべき機能
• 1（軽微）：5 ファイル未満、または 100 行未満、または軽微な修正、または小規模な改善

互換性

echo "$WERK_FIELDS" | jq -r '.compatible' からキーを選択します。

• no：「互換性あり」か「破壊的変更」かという変更項目の判断に基づいて決定します。
  • 次の点も考慮してください。
    • コミットメッセージに「breaking」、「incompatible」、「migration required」と記載されている場合、または以下に該当する場合：
    • 既存のコードに影響する API の変更
    • 設定形式の変更
    • 機能の削除やオプションの名称変更
    • コマンドラインインターフェイスの変更
• yes：修正およびほとんどの機能では、デフォルトで互換性ありとします

ステップ 3：Werk の説明を作成する

.claude/skills/werk/style-guide.md のスタイルガイドに従います。

ステップ 4：開発者に提示してレビューを受ける

開発者に次の内容を提示します。

I've analyzed the commits and prepared this werk:

Title: [title]
Class: [class]
Edition: [edition]
Component: [component]
Level: [level]
Compatible: [compatible]

Description:
---
[generated description]
---

Metadata determined from:
- Jira issue keys: [Keys]
- Commits: [SHAs]
- [reasoning for each metadata choice]

Would you like to:
1. Create werk as-is
2. Edit metadata
3. Edit description
4. Cancel

ステップ 5：開発者からのフィードバックに対応する

開発者が編集を希望する場合：

• メタデータを編集：AskUserQuestion を使用して選択肢を提示します。$WERK_FIELDS から有効なキーを提示します。
• 説明を編集：開発者が修正したテキストを入力できるようにします
• キャンセル：作成せずに終了します

ステップ 6：Werk を作成する

承認されたら、werk ファイルを作成します。 古い Werks に含まれる、無効な可能性のあるフィールドに惑わされないでください。

# Set these from the metadata determined in Step 2.
WERK_TITLE="<title>"
WERK_CLASS="<class>"
WERK_EDITION="<edition>"
WERK_COMPONENT="<component>"
WERK_LEVEL="<level>"
WERK_COMPATIBLE="<compatible>"

# Validate all keys against $WERK_FIELDS before creating
echo "$WERK_FIELDS" | jq -e --arg k "$WERK_CLASS"      '.classes | index($k)'      > /dev/null
echo "$WERK_FIELDS" | jq -e --arg k "$WERK_EDITION"    '.editions | index($k)'     > /dev/null
echo "$WERK_FIELDS" | jq -e --arg k "$WERK_LEVEL"      '.levels | index($k)'       > /dev/null
echo "$WERK_FIELDS" | jq -e --arg k "$WERK_COMPATIBLE" '.compatible | index($k)'   > /dev/null
echo "$WERK_FIELDS" | jq -e --arg k "$WERK_COMPONENT"  \
  '(.components + [.edition_components[][]]) | index($k)' > /dev/null

# Write description to temp file (preserves formatting)
# --description-file requires an absolute path
WERK_DESC_FILE=$(mktemp /tmp/werk-desc-XXXXXX.md)
cat > "$WERK_DESC_FILE" <<'DESC_EOF'
<description text here>
DESC_EOF

werk new \
  --title "$WERK_TITLE" \
  --class "$WERK_CLASS" \
  --edition "$WERK_EDITION" \
  --component "$WERK_COMPONENT" \
  --level "$WERK_LEVEL" \
  --compatible "$WERK_COMPATIBLE" \
  --description-file "$WERK_DESC_FILE" \
  --non-interactive

rm "$WERK_DESC_FILE"

werk ツールは次の処理を行います。

• stash から werk ID を割り当てます
• .werks/[ID].md ファイルを作成します
• werk を検証します
• Git に追加してコミットします
• コミットメッセージに Werk のテキストを反映します

提供されたスクリプトを使用し、コミットメッセージ内の Werk のテキストを該当する Jira の課題キーに置き換えます。

.claude/skills/werk/amend_werk_commit.sh <jira_key1> [<jira_key2> ...]

このスクリプトは、既存のコミット件名から Werk ID とタイトル（FIX/SEC のプレフィックスを含む）を取得し、メッセージを次の形式に整えます。

Add Werk #[ID]: [Title]

[Jira issue keys, one per line]

ステップ 7：成功を報告する

開発者に次の内容を伝えます。

✓ Werk [ID] created successfully
✓ Committed to git

View werk: werk show [ID]
Edit werk: werk edit [ID]

エラー処理

無効なコンポーネント：.werks/config にある有効なコンポーネントを提示し、開発者に選択を依頼します 検証に失敗：エラーを表示し、修正したうえで再試行するよう提案します Git の競合：自動解決するかどうかを開発者に確認します 依存関係の不足：必要なものを説明します

重要な注意事項

• werk コマンドを実行する前に、必ず venv を有効化します：source .venv/bin/activate
• werk コマンドはリポジトリのルートから実行します
• werk ツールがすべての Git 操作を自動で処理します
• Werk ID は stash システムで管理されます。手動で割り当てないでください
• 検証は自動で行われます。無効な werk は拒否されます

設定ファイル

• .werks/config - コンポーネントとエディションの定義
• .werks/first_free - 次に利用可能な werk ID
• ~/.cmk-werk-ids - 個人用の werk ID stash

成功のためのヒント

1. コミットをよく読む - 何が、なぜ変更されたのかを理解します
2. 迷ったら質問する - 誤った推測をするより、確認するほうがよいです
3. 例を確認する - 既存の、よく書かれた werk から学びます
4. 判断の根拠を検証する - 各メタデータの値を選んだ理由を説明します