以前、次の記事でCodexを使ってノーコーディングで作ったPythonツールを紹介しました。
今回、AGENTS.mdとPLANS.mdを使う開発方法に興味を持ち、どこまでノーコーディングで進められるのかを確かめたいと考えました。
ChatGPTに相談しながら方向性を決めて、ログフィルターのCLIツールをCodexで作ってみました。
最終的にはコード、ドキュメントも一切書かずに、AGENTS.mdとPLANS.mdだけで開発ができたので、実際に行った手順をこの記事では紹介します。
この記事は2025年11月に確認しています。
この記事で紹介するログフィルターCLIは、日付で絞り込む・特定のキーワードを含む行だけ抽出するといった処理を、シンプルなコマンド1本で行えるツールです。
実際に動かすと、次のような結果になります。
日付で絞り込む例
PYTHONPATH=src python -m logfilter_cli.cli tests/data/sample.log --date-from 2025-01-04 --date-to 2025-01-05
2025-01-04 info backup verification passed
2025-01-05 ERROR cache miss storm
2025-01-05 CRITICAL database unavailable「error」を含む行だけ抽出する例
PYTHONPATH=src python -m logfilter_cli.cli tests/data/sample.log --contains error
2025-01-03 ERROR payment queue stalled
2025-01-05 ERROR cache miss storm
2025-01-09 ERROR release rollback triggered
2025-01-12 error fraud detection alert日付＋キーワードの複合フィルター例
PYTHONPATH=src python -m logfilter_cli.cli tests/data/sample.log --contains error --date-from 2025-01-03 --date-to 2025-01-06
2025-01-03 ERROR payment queue stalled
2025-01-05 ERROR cache miss stormこの記事で分かること
動作環境
私が使った環境は次の通りです。
- Windows WSL
- Python3.13
- GitHubリポジトリ
- uv
AGENTS.mdとPLANS.md
Codexを使って開発を進めるとき、「AGENTS.md」と「PLANS.md」という2つのファイルを聞くことがあります。
名前だけを見ると難しそうですが、実は役割はとてもシンプルで、どちらもCodexにやってほしい内容を伝えるための説明書です。
AGENTS.mdとは
AGENTS.md は、プロジェクトの仕様書です。
Codexに向けて「何を作るのか」「どんな動きをしてほしいか」をまとめておくファイルです。
例えるなら、Codexに渡す”設計図”と考えるとわかりやすいです。
次のような内容を書きます。
- このツールは何をするものか
- ファイル構成はどうなっているか
- どんな入力と出力があるか
- READMEに書くべき内容
- テスト方針
PLANS.mdとは
PLANS.md は作業手順書です。
Codexが「どの順番で何をすればいいのか」を迷わないために書くものです。
こちらはCodexの行動スケジュール表”と考えるとわかりやすいです。
次のような内容を書きます。
- まず空ファイルを作る
- 次にテストを書く
- 次にテストに合わせて実装する
- cli.pyを作る
- 最後にREADMEを生成する
補足
実は、AGENTS.mdとPLANS.mdの名前でなくても動きます。
Codexは指定されたファイルを読むだけなので、ファイル名を変えても動きます。
ただ、OpenAIが推奨しているのはAGENTS.md、PLANS.mdなので、この名前を使った方がわかりやすいです。
AGENTS.mdとPLANS.mdの置き場は決まっていないです。
どこに置いてもCodexは読み取ることができますが、Codexで読み取るパスを正しく伝える必要があります。
参考URL
AGENTS.mdとPLANS.mdについてさらに詳しいことを知りたい方は次のサイトを確認してみてください。
https://github.com/openai/agents.md
https://agents.md
https://cookbook.openai.com/articles/codex_exec_plans
今回作るツール
今回作るツールはログフィルターCLIで、ログファイルを日付や特定な文字で抽出するシンプルなコマンドラインツールです。
この記事では、最終的に次のようなディレクトリ構成のツールが自動生成されます。
logfilter-cli
├─ AGENTS.md
├─ PLANS.md
├─ pyproject.toml
├─ src
│ └─ logfilter_cli
│ ├─ init.py
│ ├─ cli.py
│ ├─ parser.py
│ └─ filters.py
└─ tests
├─ test_parser.py
├─ test_filters.py
└─ test_cli.pyログファイルをキーワードや日付で絞り込む処理を行うコア部分はparser.pyとfilters.pyにまとまり、cli.pyがコマンドラインからの入力と実行を担当する作りになっています。
Codexに依頼していくと、これらのファイルが順番に生成されていくため、この記事ではその流れを具体的に紹介します。
準備
Codexに開発を指示する前、AGENTS.mdとPLANS.mdを作成し、開発に必要なものを準備します。
今回使用したGitHubリポジトリは次の通りです。
https://github.com/ojichiku/public-python-samples
今回作成するツールの仕様をChatGPTに伝えて、最初にChatGPTへAGENTS.mdとPLANS.mdの作成を依頼しました。
実際に作ったAGENTS.mdとPLANS.mdは次の通りです。
https://github.com/ojichiku/public-python-samples/blob/main/samples/logfilter-cli/AGENTS.md
https://github.com/ojichiku/public-python-samples/blob/main/samples/logfilter-cli/PLANS.md
次にGitHubで作業用のブランチを用意し、プロジェクトを初期化します。
使用したコマンドは次の通りです。
ブランチを作成します。
git switch -c feature/logfilter-cliプロジェクトを作成するディレクトリに移動して次のコマンドを実行します。
コマンドの実行後、logfilter-cli配下にプロジェクトの初期ファイルが作成されます。
Python3.13を指定するのはNuitkaが対応しているバージョンに合わせるためです。
cd samples
uv init logfilter-cli --python 3.13logfilter-cli配下にmain.pyが作成されますが、不要なため、削除しておきます。
プロジェクトの作成後、logfilter-cli配下にAGENTS.mdとPLANS.mdを配置します。
テストはpytestで実行するため、次のコマンドを使用して追加します。
pytestは開発用途で使用するため、–devをつけます。
cd logfilter-cli
# pytestは開発用途で使用するため、--devをつける
# 本番配布、Nuitkaなどのビルドでは不要になるため、uv sync --no-devとすればpytestを抜くことができる
uv add --dev pytest
uv syncここまでの手順で次のようなファイルが作成されます。
Codexによるノーコーディング開発
準備ができたのでCodexに指示して開発を行っていきます。
指示する際のポイントは、AGENTS.mdとPLANS.mdを参照させて、必要な工程を順番に依頼することです。
実際に行った手順は次の通りです。
Codexへ必要なディレクトリと空のファイル一式を作るように次のように指示します。
Codexへの指示は拡張機能を使っています。
samples/logfilter-cli配下の AGENTS.md と PLANS.md を読み込んで
必要なディレクトリと、空のPythonファイル一式を作ってください。少し待つと次のような完了メッセージが表示されます。
実際に次のようにディレクトリ、ファイルが作成されます。
私はparserとfiltersのテストを先に作る方針を取りました。
理由は、テストを先に用意するとCodexが実装を迷わず進められ、動作の基準が明確になるためです。
次のように指示してテストコードを実装します。
samples/logfilter-cli配下の AGENTS.md と PLANS.md を読み込んで
test_parser.py と test_filters.py に pytest のテストコードを実装してください。テストコードの生成後、次のように指示してプログラムを実装します。
samples/logfilter-cli配下の AGENTS.md と PLANS.md を読み込んで
テストコードに合わせて parser.py と filters.py の中身を実装してください。プログラムとテストコードが作成できたので、次のコマンドでテストを実行します。
source .venv/bin/activate
PYTHONPATH=src uv run pytest実行すると次のようなテスト結果でエラーが発生しました。
tests/test_parser.py:19: AssertionError
================================================================================================= short test summary info =================================================================================================
FAILED tests/test_filters.py::test_date_range_filter_includes_bounds_and_skips_missing_dates - AssertionError: assert [] == ['2025-11-01 ... to database']
FAILED tests/test_filters.py::test_apply_filters_combines_keyword_and_date_constraints - AssertionError: assert [] == ['2025-11-02 ...nd day error']
FAILED tests/test_parser.py::test_extract_date_parses_iso_prefix - AssertionError: assert None == datetime.date(2025, 11, 1)
=============================================================================================== 3 failed, 6 passed in 0.04s ===============================================================================================エラーが発生したので、Codexに
以下はpytestのエラーです。
原因を修正してください。
（ここにエラー内容を貼り付け）Codexが修正案を提示してコードを書き換えたあと、再度次のコマンドで実行しました。
PYTHONPATH=src uv run pytest次のように成功のメッセージが表示され、parserとfiltersが問題なく動作していることを確認できました。
=================================================================================================== test session starts ===================================================================================================
platform linux -- Python 3.13.9, pytest-9.0.1, pluggy-1.6.0
rootdir: /home/xxxx/project/public-python-samples/samples/logfilter-cli
configfile: pyproject.toml
collected 9 items
tests/test_filters.py .... [ 44%]
tests/test_parser.py ..... [100%]
==================================================================================================== 9 passed in 0.01s ====================================================================================================parserとfiltersのコードが完成したので、cli.pyの作成を依頼します。
指示はparserとfiltersと同じように、AGENTS.mdとPLANS.mdを参照させて、作成するものを指示します。
ただし、parserとfiltersとは異なり、cli.pyを先に実装してからtest_cli.pyを作成しています。
テストコードを作成した後、テストを実行して正常に完了することを確認します。
READMEの生成
最後にREADMEの作成を次のようにCodexに指示します。
samples/logfilter-cli配下の AGENTS.md を読み込んでREADME.md を作成してください。READMEまで作成できればすべての作業は完了です。
完成したコードは次のGitHubリポジトリにあります。
https://github.com/ojichiku/public-python-samples/tree/main/samples/logfilter-cli
まとめ
今回、AGENTS.mdとPLANS.mdは使い回しがしやすく、他のツール開発でも役に立つと感じました。
ノーコーディングで開発を進められたため、作業の効率を高める方法として有効だと考えています。
今後も別のツールで同じ手法を試し、その結果をまとめていく予定です。
また、CodexにはChat機能もあるので、CodexでAGENTS.mdとPLANS.mdの作成から実装まで完結できるのかも検証してみたいと思っています。
更新履歴
2025/11/30：作成するツールの実行例を追記しました。
