CHANGELOG.mdの差分から`.claude`の改善提案、一筋縄ではいかないが、少し形になってきた話

Claude Code CHANGELOGの自動監視とIssue化の試み

2026年に入ってからも日々Claudeがアップデートされていますね。

Claude Codeのアップデートを追う

以下ファイルで、リリースバージョンごとに更新内容記載されています。

作業に至ったきっかけ
ここ2カ月くらいCHANGELOG.mdを見ていますが、頻繁にバージョンアップされています。
情報を追う場合に、何か習慣をつけないと、どんどん面倒になってきてしまいます。

情報取集とリポジトリの.claudeディレクトリ最適化提案はClaude Codeにお任せして、人間は提案結果から更なる最適化を図っていく役目を担っていければと思いました。

前置きはこれくらいで、やったことを共有していきたいと思います。

構成図(v1)

Claudeのアップデートを検知して、その差分をGithubのIssue化することです。
その差分に対して、自身の.claudeディレクトリで改善ポイントがないか提案をしてもらいます。

具体的な作業ですが、単純にワークフローを1つ用意しただけです。

また、ワークフロー作成以外に必要な作業は2つです。

• .github/data/claude-code-changelog.mdを用意（ファイル名はわかれば何でも）
• 作成したファイルに、現在changelog.mdの内容をペースト

ワークフロー作成

組んだワークフローで行う処理は以下の通りです。
4が核をなす処理です。

1. 起動ログと設定内容の表示
2. CHANGELOG の取得と差分検出
3. 変更がなければ即終了
4. CHANGELOG 更新内容の処理と Issue 作成
5. 成功結果の表示と正常終了

作成時ですが、それこそ、Claudeに聞けば土台はすぐに完成しちゃいます。
細かい部分は何度かやりとりを重ねてブラッシュアップしました。

name: Claude Code CHANGELOG Monitor

on:
  schedule:
    # 火曜日 午前7時
    - cron: '0 22 * * 1'

  # 手動実行も可能に
  workflow_dispatch: {}

# Prevent concurrent runs
concurrency:
  group: changelog-monitor
  cancel-in-progress: false

permissions:
  contents: write
  issues: write

jobs:
  monitor:
    name: Monitor CHANGELOG
    runs-on: ubuntu-latest
    timeout-minutes: 10

    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
        with:
          fetch-depth: 1

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'

      - name: Install dependencies
        run: npm ci

      - name: Run CHANGELOG monitor
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          GITHUB_REPOSITORY: ${{ github.repository }}
        run: npm run monitor:changelog

      - name: Commit state file updates
        if: success()
        run: |
          git config --local user.email "github-actions[bot]@users.noreply.github.com"
          git config --local user.name "github-actions[bot]"

          # Check if there are changes to commit
          if git diff --quiet .github/data/claude-code-changelog.md; then
            echo "No changes to state file"
          else
            git add .github/data/claude-code-changelog.md
            git commit -m "chore: update Claude Code CHANGELOG state [skip ci]"
            git push
          fi

      - name: Report failure
        if: failure()
        run: |
          echo "::error::CHANGELOG monitoring failed. Check logs for details."
          exit 1

上記がワークフロー全体ですが、セットアップ処理と、gitのadd,commitくらいで
主な処理は、スクリプトで実行しています。
Run CHANGELOG monitorのnpm run monitor:changelogの通りで、package.jsonで、tsファイルを実行するコマンドを用意しています。

package.json

```json:package.json { "name": "learn-auth", "version": "0.1.0", "private": true, "scripts": { "build": "next build", "start": "next start", "monitor:changelog": "tsx .github/scripts/monitor-claude-changelog.ts", }, } ```

スクリプトでやっていたこと

最新の状態とは異なりますが、途中経過を含めて話をしていきます。
最初のスクリプトは、全体で700行でした。全体は以下リンクから確認可能です。

monitor-claude-changelog-v1.ts

構成は以下の通りです。（肝になりそうな部分は詳細を記載）

1. CHANGELOGの取得
2. 過去のCHANGELOG状態の読み込み
3. CHANGELOG差分の検出
4. 変更がない場合の早期終了
5. CHANGELOG状態ファイルの更新
6. CHANGELOG差分の日本語翻訳
7. `.claude` ディレクトリの読み取り
プロジェクト内の `.claude` ディレクトリを解析し、
Claude Code の設定・ルール・自動化構成の実態を収集する。

収集対象は以下の通り。
各領域は個別にエラーハンドリングされ、一部が欠損・未定義であっても、処理全体は継続
* `settings.json`(権限設定)
* `agents`(エージェント定義)
* `rules`(セキュリティ・運用ルール)
* `commands`(Kiroコマンド)
* `skills`(自動化スキル)

8. CHANGELOGに基づく改善点分析
検出された CHANGELOG 差分と、現在の `.claude` ディレクトリ構成を組み合わせ、
プロジェクトに対する具体的な改善提案を Claude API により生成する。分析は以下の観点で行う。
* 新機能への対応可否
* 非推奨・廃止機能に関する設定の整理
* `settings.json` における権限モデルの見直し
* エージェントの起動条件・トリガーの最適化
* ルールの重要度・優先度の再評価

各ファイル単位で、以下を明示した分析結果を出力
* 改善が必要な場合は具体的な変更提案
* 改善不要な場合はその理由

9. GitHub Issue本文の生成とIssue作成
10. 処理結果の出力と終了

実行結果(バージョン1)

作成されたIssue内容全体はこちらです。

ありがたい提案のようにも見えた

Context Engineeringにおいて重要なContextの扱い方について、どういった指示をしておくのがいいか、記載してくれている箇所がありました。これは導入してみてもいいのかな？と思える内容でした。
(後述の通り、よろしくない点がいくつかあったので、導入はしていません)

.claude/agents

役にたたない提案

逆に、アップデートの文言の文章の意味から、リポジトリに対して直結させてしまい、作業中のリポジトリに対して導入しても意味がないような記載はありました。

.claude/rules

2.1.15のアップデート：Improved UI rendering performance with React Compiler
私のリポジトリがNext.jsを用いており、それに影響されたのか、このような提案でした。

.claude/commands/kiro/

2.1.16のアップデート：Added new task management system, including new capabilities like dependency tracking
「依存」という単語に影響されたのか、Marmaidまで使っていますが、役に立たない提案でした。

Semanticな部分の判断は難しい

semanticな部分で、異なる解釈で理解する（文言に引っ張られる）問題を再認識させられました。
上記結果から、文章の意味的な解釈(Semanticな部分)の検証不足と分かりました。

そこで、最初のワークフローにおける以下2つの間に、処理を追加しました。

monitor-claude-changelog-v2.ts

8. CHANGELOGに基づく改善点分析
9. GitHub Issue本文の生成とIssue作成

以下のように、改善点分析にチェックを追加しました。
テキトーな提案を防ぐことができるか追加検証します。

8. CHANGELOGに基づく改善点分析
9. 分析結果の多角的なバリデーション
生成された分析内容に対して3段階の自動チェックを実施して、不適切な内容や誤検知を防ぐ。
* **品質チェック (Quality)**: 更新情報セクションの有無や、改善提案に具体的な動詞・ファイル参照が含まれているかを確認。
* **構文チェック (Syntax)**: 出力されたMarkdown内のJSONコードブロックが正しくパース可能か、見出し階層に跳躍がないかを確認。
* **意味チェック (Semantic)**: 未使用プラグインへの言及、内部UI等の除外対象への言及、使用技術と矛盾するフレームワークの提案がないかを確認。
10. GitHub Issue本文の生成とIssue作成

実行結果(バージョン2)

作成されたIssue内容全体はこちらです。

今度は、具体的な提案が何もない結果となりました...記載されていた情報は以下の通りです。

• 変更差分のカテゴリ分類
• リポジトリに対する影響評価
• バリデーションチェックの結果

カテゴリ分類が気持ち程度に役立つと思いましたが、その他はあまり役立ちそうにない情報でした。

変更差分のカテゴリ分類

機能追加の部分は役立つかもしれませんが、その他は特にないです。

バリデーションチェックの結果

はっきり言ってしまうと、だから？、といった状態です。
この後人間がどうすればわからない状態です。

スクリプト単体では難しい

意味的な部分で制約を設定しました。変な提案をしないようになればよかったですが、逆に厳重にルール設けすぎて、何も提案されない状態になってしまいました。

上記2つのケースを試してみて、スクリプトだけで完結させるには難しいと感じました。
そこで、skillsを追加することにしました。

スクリプトでは、差分に関するIssue作成のみ
+
差分分析用のSkillsを用意。ターミナルから、作成したIssue内容を読み込んでもらい.claudeの分析を依頼

構成図(v2)

追加部分を載せました。

ローカルでVsCodeを開きます。差分が載ったIssueからその情報を取得します。作成したskillを読み込んで、改善提案を、Issueに追記してもらう流れです。

Skillsの作成

作成したSkillはこちらです。

現在の問題点を細かく共有
このskills作成時、現在の問題点はそれなりに細かく連携の上、Plan Modeできちんと計画立てをしてもらう形で進めました。

これまで確認した2つの結果を受けて、どうしてほしいか、かなり細かく記載してみました。

#75や#95で進めているが、Claude CodeのCHANGELOG.mdの差分から、.claudeディレクトリに対する改善提案をやろうとしている。

現在は、ワークフロー時のスクリプトで差分検出のみをやってもらい、その後、実際に人間がターミナルからコマンドでその差分を載せたIssue番号をつける形で解析をやってもらっている。

それっぽい形にはなってきたが、まだ文字通りに読み込みを行いすぎて、正しい提案になっていない。
・Claude Codeが実際に動く上で改善されたポイントで、こちらで何か制御できるわけではない部分を提案されるケースがある。(メモリ管理の話や長時間セッションの安定、こちらでどう指示をしても改善する訳ない)
・タスク管理について、今回以下で記載の通り実際に導入していくつもりだが、そこに依存関係云々は関係しない
・コンテキストウィンドウのブロック制限が約65%から約98%に修正
→これもClaude Code側のバグだっただけで、その改善によって、こちらは作業は進めやすくなるが、作業リポジトリの.claudeフォルダの改善には直結しない

そこで、新しく導入されているタスク機能を導入して、今まで以上に手順化を図って、改善案や新規提案をしてほしいと思う。

考え方(非常に重要な部分)
あるアップデートの内容が、作業リポジトリの改善に直結するわけではない。
→アップデートの差分に記載された文章のうち、バグ改善とか、メモリ効率化とか、そういった話はこちらで何か対応しようがない。ある機能が追加されたり、仕様が変更されたことで、こちらができることがあるはず。そこを意識した形で改善をできればと思う。

実行結果(バージョン3)

作成されたIssue内容全体はこちらです。

機能自体の修正で、改善とは直結しない部分の除外

アップデートはあったが、私の作業リポジトリの.claude関係リポジトリの改善には直結しない箇所を除外してくれていました。

.claude/tasks関係の話

新しく導入された機能に関する提案です。生かせそうな部分はありそうですが、解像度はまだ高くありません。

.claude/settings.jsonの設定更新

これは、公式ドキュメントには記載されていないので、実際に動かしてから結果が分かりますが、
違うでしょう。

まとめ

Claude Code ChangeLogの差分をIssue化して、その差分から.claudeディレクトリの改善案提示をやってみました。少しまともな形にはなってきましたが、まだ納得いくものではありません。

もちろん、これで終わりにするのはもったいないですし、バージョン更新の差分をまとめる部分は自動化できたので、より望ましい形で発展させたいと思っています。

改善可能なポイントについて考えたとき、アップデート直後では、以下の問題があります。

• 公式ドキュメントの修正が追い付いていない
• Xなどから情報を拾うとしても、まだ情報量が少ない

更なる改善ポイント
現時点で思い浮かんでいる大きく以下2点があります。

• ある週に作成したIssueの内容に対して、skillsを適用するタイミングを少し遅らせる(1週間後)
• skillsとWebSearchを組み合わせるなどして、公式ドキュメントやXなどから、改善例を取得

今後、更なる改善を行って、よりキャッチアップと資材更新のサイクルを早められれば、と思います。

ありがとうございました。

参考資料