Agents.mdはUnixを理解し、あなたもそうすべきです

AGENTS.mdはUNIXを理解し、あなたもそうすべきです

2009年、大学のコースでApache 2 Webサーバーの設定に苦労していました。Peugeotの経験豊富なシステム管理者である教師が私の机に来て、LinuxツールとVimを使って数分で問題を解決しました。

「どうやってやったのですか？」と尋ねました。

彼は私にコマンドラインを使い始めるべきだと告げました。プログラマーとして生産的になるためには不可欠です。

家に帰ってLinuxディストリビューションをインストールし、Linuxチュートリアルとvimtutorを数セッションこなしました。それは私のキャリアにおける最高の投資の一つでした。少し呪いでもありました。試すべきツールは常にあり、調整すべき設定も常にありました。

そこから、Spacemacs、REPL、数十のCLIツールを探求し続けました。GitHubのトレンドを狂ったように追いかけ、生産性を向上させる次のものを探しました。これらのツールを使いこなし、組み合わせることを学ぶにつれて、それらの周りに作業環境を構築しました。次のステップは、そのセットアップを再現可能に保つことでした。これにより、マシンからマシンへと持ち運ぶことができます。

それが私の（レガシーな）Ansibleベースのdotfilesになりました。dotfilesとは、シェル、エディタ、その他のツールの背後にある設定ファイルであり、多くの場合、隠しファイルやディレクトリ（Fishの~/.config/fish/config.fishなど）に保存されます。セットアップスクリプトとともにリポジトリに収集されると、それらは作業環境を再構築するためのレシピになります。

これらのdotfilesを洗練させるのに何時間も費やしましたが、数分で新しいシステムをセットアップし、目の前のマシンに合わせて設定を調整できました。洗練したツールと設定は、どこで作業してもすぐに使える状態でした。これは今日のコーディングエージェントの数年前にあたります。私は人間が中心となる環境を自分で構築していました。

［画像: 人間のソフトウェアエンジニアとコンパクトなロボットが、ターミナルワークスペースを通じてUnixコマンドでコミュニケーションをとっている。］

私のdotfilesは新しいユーザーと新しいコントリビューターを獲得しました

長年、その環境のユーザーは私と私が書いたスクリプトでした。すべての改善は、ツールを見つけ、学び、設定するために私がどれだけの時間を費やせるかに依存していました。コーディングエージェントはこの関係を変えました。それらは、環境を改善する作業を手伝うことができ、その後、その結果を自分で使用できます。

エージェントに、自分たちと私のために、より良く、より速いツールを推奨させています。彼らは私が聞いたこともないツールを紹介してくれました。また、設定を検査し、変更を提案し、チェックを実行し、失敗に対処することもできます。まだ理解していない部分で助けを求めることができると、有用なdotfilesを作成することが容易になります。

利益は両方にあります。再現可能なセットアップは私の作業を軽減します。また、エージェントが操作するための予測可能な場所を提供します。有用な検証コマンドにより、変更を確認できます。また、エージェントが変更を返す前に間違いを検出することもできます。一度書かれた指示は、次のエージェントにワークフローを説明できます。

エージェントはdotfilesの改善を助け、より良いdotfilesは私たち両方がより生産的に働くのを助けます。コマンドラインでの私の長年の経験が、出発点を提供してくれました。

Unixは共通言語を提供します

エージェントにNeovimの設定を変更するように依頼することを想像してみてください。設定はファイル内のテキストです。エージェントはそれを見つけ、読み、編集し、通常のツールを使って差分を私に見せることができます。Gitが変更を記録し、別のプログラムがそれをチェックできます。私が使用することを学んだのと同じインターフェースがエージェントでも利用可能です。

これが「すべてはファイルである」の有用な部分です。Unix環境の多くは、ファイル、ストリーム、プロセスを通じてアクセス可能です。その権限内で、エージェントは設定を検査し、テストを開始し、その診断と終了ステータスを読み取り、サーバーを停止できます。具体的な結果を扱えます。

これらのツールも組み合わせることができます。一つはファイルを見つけ、一つはフィルタリングし、一つは結果を検証します。例えば、Gitリポジトリから：

git ls-files | rg '(^|/)AGENTS\.md$' 

これはツールの組み合わせです。Gitは追跡されているパスを提供し、Ripgrepはエージェント指示ファイルをフィルタリングします。2つの既存のプログラムはカスタム統合なしで協力します。より複雑なワークフローは、長くなる一方のシェルワンライナーの代わりに、明示的な入力と回復ロジックを持つ小さなPythonプログラムになる可能性があります。

これが、コマンドの品質が私たち両方にとって重要である理由です。有用なエラー、意味のある終了コード、必要に応じた構造化された出力、予測可能な非対話型動作は、ツールを使いやすく、組み合わせやすくします。見えないプロンプトでハングするコマンドは、スクリプトをハングさせるのと同じように、エージェントを立ち往生させます。私のCLI開発ガイダンスは、それらの期待を記録しています。

エージェントプラットフォームは、スケジューリング、分離、リモート調整を追加できます。ただし、ローカルコードベースでの作業については、Unixはすでに並外れた柔軟性を提供しています。1つのコマンドを改善することは、それを使用するすべてのワークフローに利益をもたらす可能性があります。

しかし、ファイルへのアクセスだけでは、エージェントが変更すべき正しいファイルかどうかはわかりません。

AGENTS.mdはこの環境の仕組みを説明します

私の現在のdotfilesはfmind/dotにあり、そこでは現在chezmoiを設定ファイルとテンプレートの管理に、miseをツール、環境、タスクの管理に使用しています。これらは、私が現在セットアップを管理する方法により適していますが、エージェントが理解する必要がある区別を導入します。インストールされた設定とその管理されたソースは異なるファイルです。

そのNeovim設定に戻りましょう。インストールされたコピーを編集するとすぐに機能するかもしれませんが、chezmoiがソースを適用するたびに消えてしまいます。私のプロジェクト指示は、永続的な編集がどこに属するか、それを検証する方法、および既存の作業をどのように保持するかをエージェントに伝えます。Unixは両方のファイルへのアクセスを提供します。AGENTS.mdはどちらを変更すべきかを説明します。

そのタスクのために、短い指示ブロックは次のようになります。

## Neovim設定の変更

- `~/.config/nvim/`ではなく、`dot_config/nvim/`の下のchezmoiソースを編集してください。
- まずGitの差分を確認し、無関係な編集とステージングされた選択を保持してください。
- 関連する設定チェックを実行し、chezmoiの差分をプレビューしてください。
- デプロイが要求されたタスクの一部である場合にのみ、設定を適用してください。

コマンドだけでは、私がどのコピーを維持しているか、またはデプロイを依頼したかどうかをエージェントに伝えることはできません。それらは指示が明示的にする決定です。

AGENTS.mdは、Agentic AI Foundationによって管理されている、プロジェクトのコンテキストと指示のためのオープンなMarkdown形式です。これは自然にここに収まります。コードの隣にある通常のテキストで、通常のツールを指し、同じ差分でレビュー可能です。Unixを必要とせず、各エージェントホストは独自のロード動作を持っています。「Unixを話す」はその適合性を表しています。

リポジトリは、環境、そのツール、およびその作業知識を一緒に保持します。アプリケーション設定はdot_config/に、共有の個人指示はdot_agents/AGENTS.mdに、再利用可能な手順はskills/に、そしてコンパニオンPython CLIはdot/にあります。リポジトリレイアウトが残りをカバーしています。

すべての手順をAGENTS.mdに含めると、それはマシン全体のマニュアルになります。Agent Skillsは、別の補完的な形式を提供します。それは、SKILL.mdのエントリポイントとサポート参照またはスクリプトを持つディレクトリです。私のスキルカタログは、ツールの使用方法、プロジェクトの開始と維持方法、および私の好みのスタックでの作業方法を説明しています。

Neovimの変更については、プロジェクト指示が作業場所と保持すべきものを確立します。関連するスキルが手順を提供します。代わりにCLIを構築するエージェントは、ストリームと終了コードに関するガイダンスをロードできます。専門知識は、すべてマニュアルをすべての会話に含めることなく利用可能です。ホストが実際にそれを発見し、従うかどうかは、実際のタスクを通じて確認する必要があります。

これらのスクリーンショットは、ソースファイルのコピーに対して実際のアプリケーションを実行している一時的なZellijセッションでキャプチャされました。ここでは、私の共有指示がNeovimでAntigravityのCLIの隣に開かれています。

［画像: 左にNeovimで開かれた私の共有AGENTS.md、右に実際のagyインターフェース。］

これで、改善には設定と、それを使用およびチェックする方法の説明の両方を含めることができます。どちらもGitに残るので、レビューでき、将来のエージェントも見つけることができます。これにより、次のタスクはより良い出発点を得られます。

より良いツールには有用なチェックが必要です

作業をチェックする指示には、その背後にある有用なコマンドが必要です。Zizmorは私のGitHub Actionsワークフローを監査し、Lefthookはコミットやプッシュの周りで設定されたチェックを実行します。それらの診断は、エージェントが修正するものと私がレビューするものをエージェントに提供します。Git-cliffはリリースノートを処理します。

チェックは実際に実行されなければなりません。Cosignは私のセットアップにインストールされていますが、ツールインストールのための自動署名と出所検証は無効になっています。マシン上のツールは、効果のある保護ではありません。

リポジトリをサポートし、ワークステーション操作を自動化するために、dotという専用のPython CLIを構築しました。TyperとPydanticで構築されており、システムメンテナンスとエージェント調整を予測可能で型付けされたコマンドに変換します。dot doctorサブコマンドはローカルヘルスとツールのパリティをチェックし、dot agent contextは指示ファイルとスキルカタログが厳密なトークン予算内に収まっていることを検証します。他のサブコマンドは、ハーネス全体でフォルダの信頼性を管理し（dot trust）、グローバルエクスポートなしでスコープ付き認証情報を注入し（dot secret）、エージェントセッション全体でトークン使用量を集計します（dot agent stats）。エージェントと人間が環境を共有する場合、堅牢なCLIは両方に必要な信頼できる契約を提供します。

エージェントがその基盤の維持を支援してくれるので、プロジェクト全体でより多くの作業を委任できます。次の課題は、それを追跡することです。

プロジェクトごとに1つのセッション、タスクごとに1つのタブ、プログラムごとに1つのペイン

私の日常のワークスペースはターミナルです。Ghosttyがそれをホストし、Fishがシェルを提供し、Zellijが並行作業を整理します。1つのセッションがプロジェクトを保持し、タブがそのタスクを分離し、ペインが各タスクを実行中のプログラムに分割します。

私のAlt+/ショートカットは、現在のタスク上にZellijのセッションマネージャーを開き、他のプロジェクトを手の届くところに置きます。

［画像: ZellijのセッションマネージャーがFishターミナル上に表示され、いくつかのプロジェクトセッションと、指示、レビュー、チェック、ツールのタブが表示されている。］

私は、あるタスクにClaude Code、別のタスクにCodex、レビューにAntigravityを使用できます。完了通知は、エージェントが終了したときに私を呼び戻すのに役立ちます。

私は電光石火の速さで動いています。少なくとも人間の速度で。

ボトルネックは、コードをレビューする私の能力のままです。エージェントは複数のタスクで作業できますが、私は最初の差分を読んでいます。それでも間違いを犯します。個別のタブは私の注意を整理します。重複する編集を防ぐには、個別のチェックアウトまたは慎重な調整が必要です。

LazyGitを使用して変更を処理し、Neovimでコードを検査・編集し、gh-dashを使用してレビュー依頼、失敗したCI、マージ準備完了のプルリクエストを見つけます。私のAlt+gショートカットは、フローティングペインでLazyGitを開くため、ワークスペースを離れることなく差分を調べることができます。

［画像: ZellijのフローティングペインにLazyGitが表示され、左にファイルリスト、右にdotリポジトリからのREADMEの差分が表示されている。］

これらのツールは、注意が必要な作業に到達するのに役立ちます。それらは私に無限の注意を与えることはできません。忙しいターミナルの壁は非常に印象的ですが、すべてのタブが同じ人間を待っている場合はそうではありません。

説明できるものを管理し続ける

その人間の責任は、環境自体にも適用されます。シェルアクセスを持つエージェントはかなりの権限を持っており、Markdownファイルにはそれをすべて含めることはできません。AGENTS.mdは指示を表現しますが、権限、認証情報、分離、およびエージェントホストが実行できることを決定します。

私のdotfilesは個人的で意見の分かれる設定です。インストール手順は、広範なエージェント権限とワークスペースの信頼について説明しています。それらを採用する前に、それらの選択を検査してください。エージェントが設定ファイルを修正できるのと同じアクセス権で、それを破損させることもできます。

レビューすべきプロジェクトが1つあるとすれば、それはあなたのdotfilesです。それらは他のプロジェクトの基盤です。エージェントは、その基盤を構築および改善しやすくし、あなたと一緒に改善から利益を得ます。私のすべての作業はオープンソースです。完全なレイアウト、エージェントスキル、およびハーネス設定は、GitHubのfmind/dotで利用可能です。

［画像: GitHub上のfmind/dotリポジトリ。プロジェクトレイアウト、エージェントスキル、および設定ディレクトリが表示されている。］

有用なツールを1つから始めてください。エージェントにそれを設定するのを手伝ってもらい、変更を検査し、プロジェクトの指示または関連するスキルに、使用方法とチェック方法を記録してもらいます。次のタスクで試してください。役立つものを保持してください。

dotfilesの究極のルールを覚えておいてください：他人のものをそのまま使用しないでください。ツールと設定を理解していない場合、あなたはマスターではありません。あなたは操り人形です。

フォークして適応させてください。それがハッカーウェイです。

さあ、あなたのdotfilesをハックしましょう。