AGENTS.md を既存の Sphinx + ablog 技術ノートに導入する#
Codex を使ってこの技術ノートを編集する機会が増えてきたため、
リポジトリ固有の作業ルールを AGENTS.md にまとめることにした。
このノートは Sphinx + ablog で作っている個人技術ブログであり、 記事作成、翻訳、ビルド、公開まわりにいくつか自分用の前提がある。
Codex に毎回それを説明するのではなく、 リポジトリの中に作業方針として置いておくことで、 作業のブレを減らせるのではないか、という試みである。
AGENTS.md とは何か#
AGENTS.md は、Codex などのエージェントに対して、
そのリポジトリでの作業方針や注意点を伝えるためのファイルである。
このノートでは、特に次のような情報を置くことにした。
日本語を基準に作業すること
Sphinx + ablog の記事配置ルール
Rye を使ったビルド手順
gettext / sphinx-intl による翻訳方針
生成物を直接編集しないこと
Netlify や GitHub Actions まわりの注意点
なぜ体験用リポジトリではなく既存 note に入れるのか#
最初は、AGENTS.md を試すためだけの小さな体験用リポジトリを作ることも考えた。
しかし、今回はあえて既存の技術ノートに直接導入することにした。
理由は、体験用リポジトリでは本当に困っていることが出にくいからである。 このノートには、すでに次のような「実運用ならでは」の前提がある。
記事本文は日本語を正とする
英語ページは翻訳版として扱う
docs/_build/配下は生成物なので直接編集しないblog_futureやblog_pathなど、変更に注意が必要な設定があるREADME に古い記述が残っている場合でも、実運用は
pyproject.tomlやdodo.pyを優先する
こうした前提は、きれいな検証用リポジトリではなかなか再現できない。
むしろ、少し歴史があり、運用上の癖もある既存 note に入れることで、
AGENTS.md がどの程度役に立つのかを見やすくなると考えた。
導入した AGENTS.md のサンプル#
今回置いた AGENTS.md の内容は、おおよそ次のようなものにした。
# AGENTS.md
## このリポジトリについて
このリポジトリは、Sphinx + ablog で作成している個人技術ブログです。
公開サイトは日本語を主軸としつつ、英語ページも公開対象にします。
ただし、運用者本人は日本語のみを理解するため、
作業説明・判断材料・提案・確認事項は必ず日本語で書いてください。
## 基本方針
- すべてのやり取り、作業説明、提案、レビューコメントは日本語で行う。
- 記事本文の元原稿は日本語を正とする。
- 英語ページは翻訳版として扱う。
- 英語翻訳を作る場合でも、意味の確認や変更理由は日本語で説明する。
## ビルド
- パッケージ管理は Rye を使う。Poetry 前提で作業しない。
```bash
rye sync
rye run doit doc
```
- ビルド成果物は `docs/_build/html` に出力される。
- `docs/_build/` 配下の生成物は原則として直接編集しない。
## 記事作成
- ブログ記事は `docs/blog/posts/` に置く。
- 記事形式は原則 reStructuredText、拡張子は `.rst` とする。
- ファイル名は `YYYY-MM-DD-slug.rst` とする。
- 記事冒頭には ablog の `post` directive を置く。
## 翻訳
- 翻訳は Sphinx gettext / sphinx-intl の仕組みを使う。
- 翻訳ファイルは `docs/locale/en/LC_MESSAGES/` 配下の `.po` ファイルを編集する。
- `.mo` と `.pot` は生成物なので、原則コミットしない。
## 運用上の注意
- README に古い Poetry 前提の記述が残っている場合がある。
- 現在の実運用は `pyproject.toml`, `dodo.py`, `netlify.toml` を優先して判断する。
- `blog_future` の設定は予約投稿運用に影響するため、変更前に必ず意図を確認する。
- `blog_path = "blog/posts"` は `/blog` と `/blog.html` の衝突回避に関係しているため、安易に変更しない。
実際に入れてみて気づいたこと#
導入してみると、AGENTS.md は単なる設定ファイルというより、
自分の運用ルールを棚卸しするためのメモにもなると感じた。
たとえば、普段なんとなく守っている次のような判断も、 明文化しておくと Codex に伝えやすい。
この記事は日本語原稿を正とする
英語版は直接書かず、翻訳として扱う
生成された HTML や mo ファイルは直接編集しない
ビルドは Poetry ではなく Rye を使う
自分では当たり前だと思っていたことほど、 エージェントにとっては明示されていない前提になりやすい。
その意味で、AGENTS.md を書く作業は、
自分の技術ノートの運用を言語化する作業でもあった。
まだ迷っていること#
一方で、どこまで細かく書くべきかはまだ迷っている。
あまり細かく書きすぎると、AGENTS.md 自体が古くなりやすい。
逆に抽象的すぎると、Codex が実際に作業するときの判断材料としては弱い。
今のところは、次のような基準で書くのがよさそうだと考えている。
間違えると公開物に影響することは書く
自分が毎回説明していることは書く
生成物と手書きファイルの区別は書く
ツール選択に関わることは書く
一時的な好みや未確定の運用は書きすぎない
今後の展望: Skills も導入してみたい#
AGENTS.md でリポジトリ全体の方針を伝えられるようになったので、
次は Skills の導入も試してみたい。
AGENTS.md が「このリポジトリでの基本方針」だとすると、
Skills は「特定の作業をするときの手順書」として使えそうである。
たとえば、この技術ノートでは次のような Skills が考えられる。
新規 ablog 記事を作る Skill
日本語記事から英語翻訳用 po ファイルを更新する Skill
Sphinx ビルドエラーを調査する Skill
Netlify 公開前の確認を行う Skill
まずは、記事作成と翻訳まわりから小さく試してみるつもりである。
おわりに#
AGENTS.md を導入したことで、Codex に毎回説明していた前提を、
リポジトリ側に持たせられるようになった。
特に、既存の Sphinx + ablog 技術ノートのように、 記事、翻訳、ビルド、公開がゆるくつながっているリポジトリでは、 こうした作業ルールの明文化が効きそうである。
まだ導入したばかりなので、今後の作業の中で少しずつ育てていきたい。
記事情報
- 著者:
mtakagishi
- 公開日:
2026-05-10