Skip to content

エージェントへの指示を AGENTS.md の 1 つにして CLAUDE.md を置かず、規則と正の文書を指す行だけを書く - #654

Open
neguse wants to merge 2 commits into
masterfrom
docs/agent-entry
Open

neguse wants to merge 2 commits into
masterfrom
docs/agent-entry

Conversation

@neguse

@neguse neguse commented Nov 21, 2026 •

Copy link
Copy Markdown
Owner

問題

エージェントへの指示の入口が 3 つあった (CLAUDE.md、AGENTS.md、tcs/CLAUDE.md)。
AGENTS.md は CLAUDE.md と docs の英語の要約で、そこにしか無い規則と、特定の機械の WSL の path があった。
CLAUDE.md は CI の job の一覧、tcs の探し方、web の build と検査、.NET 実行の細部を写していて、写しの一部は実装と合っていなかった。

  • scripts/pre-push.sh を「CI と同内容の手動ゲート」としていたが、pre-push は windows、macos、web-export、入口の page の検査、tcs 自身のテスト、release の一式に当たるものを走らせず、CI が外している lavapipe の golden を比べる。
  • lub <csproj> に dotnet SDK が要るとしていたが、lub は実行ファイルの隣の C の tcs を先に使う。
  • release の一式は PR では走らないとしていたが、ci.yml の kit job は PR でも走り、gate が待つ。

変更

  • 指示は AGENTS.md と tcs/AGENTS.md に置き、CLAUDE.md と tcs/CLAUDE.md は消す。Claude Code (v2.1.277 以降) は、作業のディレクトリとその上に CLAUDE.md が無いときに AGENTS.md を読み、サブディレクトリの AGENTS.md はそこの file を読むときに読む。CLAUDE.md がどこかにあると AGENTS.md は読まれないので、置かないことを AGENTS.md に書く。docs/README.md と docs-lint の現状ドキュメントの一覧からも CLAUDE.md を外す。
  • AGENTS.md に、同じ規則や事実を 2 か所に書かない約束を足す (code は正の実装を呼び、文書は正の文書を指す。写すしかないときは一致を確かめる検査を同じ PR に入れる)。
  • 写していた事実は、正を指す行にする。
    • CI の job と走り分け: .github/workflows/ci.yml の各 job の先頭のコメント
    • build、実行、整形、サンプルの置き方、runtime テストと golden: README.md
    • tcs の探し方、C# の書き方、.NET 実行: docs/manual/08-csharp.md
    • web の build と検査: web/README.md
    • 生成物の一覧: docs/api-glue.md
  • 前の AGENTS.md にしか無かったもののうち、Release build と benchmark の手順は docs/release-build.md と docs/sprites-bench.md に既にある。sandbox が build を止めたときの扱いだけを AGENTS.md に残し、WSL の path は消す。
  • 前の CLAUDE.md にしか無かった事実は、正の文書に移す。
    • runtime テストの書き方 (tests/cs/<Entry>.cs と 1 行の csproj、一覧は scripts/cs-tests.sh、合否は tests/cs/Check.cs の先頭のコメント): README.md の「runtime テスト」
    • サンプルの data の置き方 (samples/data/ と samples/<name>/data/) と、sample の名前での起動: README.md の「実行」
    • 前からある build/wasm の generator が preset と合わないときの build、lub.js の構文の検査、docs の page の作られ方: web/README.md
  • scripts/pre-push.sh の先頭のコメントに、PR の CI との違いを書く。

確かめたこと

  • scripts/docs-lint.sh が通る。
  • Claude Code の docs (https://code.claude.com/docs/en/memory.md の AGENTS.md の節) で、CLAUDE.md が無いときに AGENTS.md を読むことと、サブディレクトリの AGENTS.md の読み方を確かめた。
  • 移した事実は実装で確かめた: tests/cs/Check.cs の先頭のコメント、src/main.c の sample の名前の解決、web/package.json の dev と build が gen-api を走らせること、scripts/pre-push.sh が走らせるものと CI の job。

入れなかったもの

Refs #649

🤖 Generated with Claude Code

https://claude.ai/code/session_01Bkc8zTBHyUd33xex3cycYb

CLAUDE.md は AGENTS.md を読み込む 1 行 (@AGENTS.md) にする。tcs/ も同じく、指示を tcs/AGENTS.md に置き、tcs/CLAUDE.md はそれを読み込む。
前の AGENTS.md にしか無かった手順は docs/release-build.md と docs/sprites-bench.md に既にあり、特定の機械の path は消す。
AGENTS.md に、同じ規則や事実を 2 か所に書かない約束を足す。
前の CLAUDE.md が写していた CI の job の一覧、tcs の探し方、web の build と検査、.NET 実行の細部は、正 (ci.yml の各 job の先頭のコメント、README.md、docs/manual/08-csharp.md、web/README.md、docs/api-glue.md) を指す行にする。
そこにしか無かった事実 (runtime テストの書き方、サンプルの data の置き方と sample の名前での起動、wasm の build の generator の食い違い、lub.js の構文の検査、docs の page の作られ方) は README.md と web/README.md に移す。
scripts/pre-push.sh の先頭のコメントに、PR の CI との違いを書く。

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Bkc8zTBHyUd33xex3cycYb
@neguse
neguse marked this pull request as ready for review November 21, 2026 07:36
Claude Code は、作業のディレクトリとその上に CLAUDE.md が無いときに AGENTS.md を読み、サブディレクトリの AGENTS.md もそこの file を読むときに読む。
CLAUDE.md がどこかにあると AGENTS.md は読まれないので、AGENTS.md に CLAUDE.md を置かないことを書く。

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Bkc8zTBHyUd33xex3cycYb
@neguse neguse changed the title エージェントへの指示を AGENTS.md の 1 つにし、規則と正の文書を指す行だけを置く エージェントへの指示を AGENTS.md の 1 つにして CLAUDE.md を置かず、規則と正の文書を指す行だけを書く Nov 21, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant