Adding AGENTS.md to an Existing Sphinx + ablog Technical Note

As I have been using Codex more often to edit this technical note, I decided to collect the repository-specific working rules in AGENTS.md.

This note is a personal technical blog built with Sphinx and ablog. It has a handful of assumptions around writing posts, translation, builds, and publishing.

Rather than explaining those assumptions to Codex every time, I wanted to see whether keeping them inside the repository as working guidelines would make the workflow more consistent.

What Is AGENTS.md?

AGENTS.md is a file for telling agents such as Codex how work should be done in a particular repository, including the project?s conventions and caveats.

For this note, I decided to include information such as:

• Use Japanese as the baseline language for work

• Where Sphinx + ablog posts should be placed

• How to build the site with Rye

• The translation workflow using gettext and sphinx-intl

• Do not edit generated files directly

• Notes about Netlify and GitHub Actions

Why Put It in the Existing Note Instead of a Demo Repository?

At first, I considered creating a small demo repository just to try out AGENTS.md.

This time, though, I chose to add it directly to my existing technical note.

The reason is that a demo repository rarely exposes the problems that actually matter. This note already has several assumptions that only show up in real day-to-day use:

• The Japanese article is treated as the source of truth

• English pages are treated as translations

• Files under docs/_build/ are generated and should not be edited directly

• Settings such as blog_future and blog_path need to be changed carefully

• Even if the README still contains old notes, the actual workflow should be judged from pyproject.toml and dodo.py

Those kinds of assumptions are hard to reproduce in a clean test repository.

By putting it into an existing note with a bit of history and a few operational quirks, I thought it would be easier to see how useful AGENTS.md really is.

Sample AGENTS.md

The AGENTS.md I added looks roughly like this:

# 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` の衝突回避に関係しているため、安易に変更しない。

What I Noticed After Adding It

After adding it, I found that AGENTS.md is not just a configuration file. It also works as a way to take inventory of my own operating rules.

For example, decisions I usually follow without thinking become much easier to communicate to Codex once they are written down:

• The Japanese draft is the source of truth for the article

• The English version is not written independently; it is handled as a translation

• Generated HTML and .mo files should not be edited directly

• Builds should use Rye, not Poetry

The things that feel obvious to me are often exactly the assumptions that are invisible to an agent.

In that sense, writing AGENTS.md was also an exercise in putting the workflow for my technical note into words.

Open Questions

At the same time, I am still unsure how detailed it should be.

If I make it too detailed, AGENTS.md itself may become outdated quickly. If it is too abstract, it will not give Codex enough practical guidance when it actually works in the repository.

For now, I think the following criteria are a reasonable starting point:

• Write down anything that could affect the published site if handled incorrectly

• Write down anything I find myself explaining repeatedly

• Make the distinction between generated files and hand-written files explicit

• Document decisions that affect tool choice

• Avoid over-documenting temporary preferences or unsettled practices

Next Step: Trying Skills

Now that AGENTS.md can communicate repository-wide guidelines, I would also like to try introducing Skills next.

If AGENTS.md is the set of general guidelines for this repository, Skills seem useful as playbooks for specific tasks.

For this technical note, I can imagine Skills such as:

• A Skill for creating a new ablog post

• A Skill for updating English .po files from Japanese articles

• A Skill for investigating Sphinx build errors

• A Skill for pre-publication checks before deploying to Netlify

I plan to start small, probably around article creation and translation.

Closing Thoughts

By adding AGENTS.md, I can now keep the assumptions I used to explain to Codex every time inside the repository itself.

This kind of explicit working rule seems especially useful in an existing Sphinx + ablog technical note, where writing, translation, builds, and publishing are loosely connected.

I have only just introduced it, so I would like to keep improving it gradually as I continue working on the note.

Article Information

Author:

mtakagishi

Published:

2026-05-10

Updated pre-commit template (mypy compatible and default Python specified)   AGENTS.md の次に、翻訳作業を Skills 化してみる