コーディングエージェントのハーネスとして Hook を活用したいと思い調べていたところ、開発環境の管理ツールである mise を開発した @jdx さんが hk というツールを開発していることを知った。hk は Git Hook Manager というキャッチフレーズではあるものの、使っていくとコーディングエージェントの Hook にも使えるし、Hook に限らず Linter や Formatter を管理するツールとして CI で呼び出すこともできて、しかも有名なツールに対する設定があらかじめ用意されていてと、とにかく使いでのあるツールだと感じた。

言語ランタイムのバージョン管理にとどまらない何でもありのツールとして進化した mise と組み合わせると、Linter や Formatter を導入してチェックを適用するまでのフローがこれまでになく簡単になる。とにかく簡単に Linter や Formatter を導入していけるので、リポジトリ内のメインの言語ではないファイル (JSON とか YAML とか Markdown とか) もちゃんときれいにしておこうという気持ちになれる。

具体的には以下のページに対応しているツールのリストがある。もちろん、ここになくても CLI のコマンドがあれば対象ファイルを指定するくらいで簡単に導入できる。

• Built-in Linters Reference | hk

導入して Git Hook で活用するのは公式のドキュメントを見れば簡単にできることなので、ここでは、Claude Code の Hook や GitHub Actions で利用した事例を紹介する。

Claude Code の Hook での利用

Claude Code などのコーディングエージェントがファイルを編集した直後に Hook で強制的に Lint や Format を実行することで、問題があればすぐにフィードバックできる。対応しているツールなら自動修正もできるので、自動で解決しなかった問題への対応に集中させられる。

具体的には、hooks に Claude Code に設定するための Hook を定義しておいて、hk run コマンドで指定すればよい。以下の例では、jq と xargs を使うことで、Claude Code が操作したファイルを hk に渡して、最小限のファイルだけに Lint や Format が適用されるようにしている。

amends "package://github.com/jdx/hk/releases/download/v1.45.0/hk@1.45.0#/Config.pkl"
import "package://github.com/jdx/hk/releases/download/v1.45.0/hk@1.45.0#/Builtins.pkl"

local linters = new Mapping<String, Step> {
    // ...
}

hooks {
  ["post-tool-use"] {
    fix = true
    steps = linters
  }
}

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs -I{} hk run post-tool-use {}"
          }
        ]
      }
    ]
  }
}

GitHub Actions での利用

hk には hk check や hk fix というサブコマンドがあり、Git などの Hook とは関係なく CLI で呼び出して設定済みの Linter や Formatter を実行できる。これを GitHub Actions から呼び出してあげればよい。CI で Linter や Formatter を使うためにわざわざ hk を挟まなくてもよいのでは、と思うかもしれないが、個人的には、設定を hk.pkl に寄せて Hook と一元管理できるのは結構うれしい。Node でいうところの package.json の scripts とかの言語固有のものは捨ててしまって、すべてを hk に寄せる勢いで使うと良さを実感できると思う。

amends "package://github.com/jdx/hk/releases/download/v1.45.0/hk@1.45.0#/Config.pkl"
import "package://github.com/jdx/hk/releases/download/v1.45.0/hk@1.45.0#/Builtins.pkl"

local linters = new Mapping<String, Step> {
    // ...
}

hooks {
  ["check"] {
    steps = linters
  }
}

GitHub Actions で使う hk は mise で入れてしまうと楽。先述の通り、hk から呼び出す Linter や Formatter も mise に寄せてしまうと非常に快適になる。

[tools]
hk = "1.45.0"

hk check --all でリポジトリのすべてのファイルを対象にチェックを実施できる。

steps:
- uses: actions/checkout@v6
- uses: jdx/mise-action@v4
- run: |
    hk check --all
  env:
    HK_PKL_BACKEND: pklr