READMEを実行するGo製タスクランナー「xc」のススメ

忙しい人まとめ

2025-07-11 職場のプロジェクトに必ず配置しちゃうMakefileの話 がバズってるのを見かけ、xcを広めなければ、、、という義務感に駆られたのでこの章を追加しました。
タイトルも一部変更しました。

• GoやDockerなど、タスクランナー（コマンドメモ）が存在しない環境ではしばしばmakeがタスクランナーとして使われる
  • 大体の環境にデフォルトでインストールされているのが良い
  • .PHONYまみれ、複雑すぎるhelpコマンドが書かれたMakefile、、、
  • そもそもmakeはタスクランナーとして作られてないし！！
• Goの環境ではTaskやMageが使われがち
  • makeとは違い各々がインストールしないと使えない
• xcっていうタスクランナーがあります
  • README.mdにタスク（シェルスクリプト）を記述する
    • e.g. ### Buildの下にコマンドを書くとxc buildが使える
  • xcをインストールするのが面倒ならまずはREADMEからコピペして実行すれば良い
  • Makefileにタスクを書いて、そのタスクの使い方をREADMEに書いて、、、みたいなことをする必要がない
• 開発者もLLM Agentもまず最初に見るのはMakefileではなくREADMEである、READMEを充実させてxcを使おう

Goにおけるタスクランナーの歴史

npmならnpm run、denoならdeno taskなど言語ツールにタスクランナー機能が付属していることがありますが、Goではそのような機能は提供されていません。

そこでGoのプロジェクトではMakefileがタスクランナーとして用いられることがしばしばありますが、独自の文法、.PHONYを大量に書く必要がある、Makefile警察が飛んでくる、などの問題があります。

Makefile警察「ぐぬぬぬ…」 #taskfile - Qiita

https://qiita.com/schrosis/items/12b4361c528819d13901

タスクランナーとしてMakefileを使うことから脱却すべく、巷ではYAMLベースの「Task」やGoベースの「Mage」が用いられている印象です。

どちらも多少試したことはありますが、主に以下の点が気になりました。

• Taskfile.ymlやmagefile.goといったツール独自のファイルを置く必要がある
  • これはMakefileも同様
• Go製とはいえプロジェクトメンバー全員がツールのインストールを半強制される
  • makeは大体のLinux環境に入っているためギリ許せる
  • go runで動かせるとはいえコマンドが長い
  • コマンドを短く実行したくてタスクランナーを使っているのに...
• (主にMage) シェルスクリプトに近い形で書きたい
  • os.Exec("docker", "compose", "up", "-d") のようには書きたくない
  • 目的はコマンドを短く実行することであってGoでコマンドを実行することではない
  • そこまで複雑なエラーハンドリングも必要ない

他に良いGo製のタスクランナーがないか探していたところ、「xc」というMarkdownベースのタスクランナーを見つけました。

https://xcfile.dev/

https://xcfile.dev/

https://github.com/joerdav/xc

https://github.com/joerdav/xc

Markdown内のコマンドを実行するツールはGoogleが作っているTypeScript製の「zx」が有名ですね。

---

2024-07-24追記：似たツールに「runme」があるそうです。企業が管理しているOSSでxcより開発が盛んなため、runmeの方が安定感があるかもしれません（Goとnpmでインストールできるのも結構嬉しそうです）。本記事ではxcの解説をします。

https://runme.dev/

https://x.com/yasushia/status/1815890398562378023

---

7/24追記：traP内だとtraPortfolioというレポジトリでxcが使われています。使い方の参考になるかもしれません。

xcの利点

xcはタスクの処理とドキュメントが分離している問題を解決するために作られたそうです。通常のタスクランナータスクを専用のファイル（Makefile、package.jsonなど）に記述した上でさらにそのタスクの使い方をREADMEに書く必要がありますが、xcではその必要はありません。

The problem xc is intended to solve is scripts maintained separately from their documentation. Often a Makefile or a package.json will contain some useful scripts for developing on a project, then the README.md will surface and describe these scripts. In such a case, since the documentation is separate, it may not be updated when scripts are changed or added. xc aims to solve this by defining the scripts inline with the documentation.

VSCode拡張も用意されており、ワンタップで実行することもできます。

また、先ほど挙げたTaskやMageの課題はxcによって解決することができます。

• 独自のファイルを置く必要がある
  • README.mdはどのプロジェクトにも基本置かれる
• ツールのインストールを半強制される
  • 1回しかタスクを実行しなければREADMEからコマンドをコピペするだけでOK
  • 繰り返し実行したくなった時に初めてxcをインストールすれば良い
  • (言語にタスクランナーが付属していればこんな問題は...)
• シェルスクリプトに近い形で書きたい
  • コードブロック内に直接シェルスクリプトを書くことができる

xcの機能紹介

xcの機能はシンプルで、README.mdに各タスクのコマンドを記述することでそれらがxcを通して実行することができるようになります。

以下のようにTasksというHeadingを置き、その下に各タスクの処理をコードブロック内に記述します。
説明や設定（Required:、Inputsなど）も書くことができます。

(... READMEに書くべき諸々のこと)

# Tasks

## test

Test the project.

```bash
go test ./...
```

## tag

Deploys a new tag for the repo.

Specify major/minor/patch with VERSION

Inputs: VERSION

Requires: test

```bash
NEW_TAG=... # Inputsを使って処理を行う
git tag ${NEW_TAG}
git push origin ${NEW_TAG}
```

その後、xcを実行することでREADMEに記述したコマンドをタスクとして実行することができます。

xc tag major

xcの（まだ）イマイチなところ

まだいくつかイマイチなところもありますが、今のところ最低限の機能は使えています。

• カラー対応が貧弱
  • PR出した https://github.com/joerdav/xc/pull/119
• Task（10k）やMage（4k）に比べるとスターが少ない（1k）
  • 応援してあげてほしい

xcを使おう

xcの紹介でした。

https://xcfile.dev/

https://xcfile.dev/