AGENTS.md Starter Kit: Minimal and Advanced Templates for Codex and Any Agent

## What is it, and what problem does it solve? AGENTS.md is a file placed at the root of a project, written for "AI coding agents" to read — essentially a project's README, except the reader is an agent like Codex or Claude Code. It tells the agent how to install the project, how to run tests, what coding style to use, and what the safety red lines are. The pain point is very concrete: without it, an agent has to guess your conventions every time it enters the project, and often ends up using the wrong package manager, the wrong naming style, or performing destructive operations. Ischca's awesome-agents-md is a curated collection of real-world AGENTS.md examples, templates, guides, and tools, built around the goal of "accelerating agent onboarding" — getting an agent up to speed the moment it enters a project. ## Why this source is worth using It offers two clearly positioned templates that cover two different starting points: - **Minimal**: "a concise, no-frills starting point" — a single-section minimal checklist (runtime, install command, test command, formatting, one network-security restriction) you can be running with in five lines. - **Advanced**: "a feature-rich template with testing, safety and style rules" — covering five sections: Overview, Environment, Testing, Coding Conventions, and Safety, plus Example Tasks demonstrating typical assignments. The advanced template contains several hard rules well worth borrowing, such as "a commit must leave the test suite fully green," "use kebab-case for filenames," "never build shell commands from user input," and "no unauthorized sudo." And the whole repo is CC0 (public domain dedication) — the most permissive license possible, so you can freely adapt it. ## How to use it (steps and key points) This entry's full prompt rewrites both the minimal and advanced skeletons into "fill-in-the-blank" versions, ready to copy straight into your project root's AGENTS.md: 1. **New or small projects**: start with Template A (minimal) — just fill in the five blanks {{NODE_OR_RUNTIME}}, {{INSTALL_CMD}}, {{TEST_CMD}}, {{FORMAT_CMD}}, and {{ALLOWED_ENDPOINT}} and you're ready to go. 2. **Larger or multi-person projects**: upgrade to Template B (advanced) — fill in the environment (Docker/services), test-layer breakdown, naming and style conventions, safety boundaries, then add two Example Tasks so the agent knows what a typical assignment looks like. 3. Place the file at the repo root; most agents, including OpenAI Codex, read it automatically. Subdirectories can also have their own AGENTS.md for local overrides. ## When to use it Any repo you hand off to an AI agent for collaboration should have one. When starting a new project, or when you want Codex/Claude Code to follow the rules quickly, start with minimal; once the project grows a test suite, CI, and security requirements, switch to advanced. It complements documents like CLAUDE.md or an Agent OS standards file — AGENTS.md is the agent's "entry rulebook," and the more precise it is, the less likely the agent is to go off the rails. ## Source and license Source: Ischca/awesome-agents-md (by Ischca, CC0 1.0 Public Domain Dedication) — this entry is an edited adaptation; see the link above for the original. The original repo also includes multiple real-world AGENTS.md files (including a production-grade Java SDK example), guides, and tools; this entry only adapts the structure of its minimal/advanced templates into fill-in-the-blank starters, and does not reproduce the full template files verbatim.

填下面的欄位，上方 prompt 會即時替換 [方括號] 內容。填好後按「複製組好的 prompt」直接丟進工具。

# === 範本 A：Minimal AGENTS.md（5 行就上路）===
# AGENTS.md

- 使用 {{NODE_OR_RUNTIME}}（例：Node 22 LTS）。
- 安裝相依套件：`{{INSTALL_CMD}}`（例：pnpm install）。
- 跑測試：`{{TEST_CMD}}`（例：pnpm test）。
- 格式化程式碼：`{{FORMAT_CMD}}`（例：pnpm format / Prettier）。
- 安全限制：除了 {{ALLOWED_ENDPOINT}} 之外，不得呼叫任何外部網路端點。

# === 範本 B：Advanced AGENTS.md（含 5 大區塊 + 範例任務）===
# AGENTS.md

## Overview
{{PROJECT_OVERVIEW}}（例：以 pnpm workspaces 驅動的模組化 TypeScript monorepo，採用 Airbnb + Prettier 風格）。

## Environment
- 本機開發：`{{DEV_CMD}}`（例：pnpm dev）。
- 相依基礎設施：{{INFRA}}（例：需要 Docker；`docker compose up -d` 啟動 Postgres 與 Redis）。

## Testing
- 單元測試：`{{TEST_CMD}}`。
- 整合測試：{{INTEGRATION_NOTE}}（例：需先啟動 Docker）。
- 鐵則：一個 commit 必須讓測試套件保持全綠。

## Coding Conventions
- 命名：檔名用 kebab-case；{{COMPONENT_LOCATION}}（例：React 元件放在 /src/components）。
- 風格：偏好函式式寫法，避免全域可變狀態。
- 其他：{{EXTRA_CONVENTIONS}}。

## Safety
- 禁止用使用者輸入直接拼出 shell 指令。
- 未經人類授權不得使用 `sudo` 或執行破壞性操作。
- {{EXTRA_SAFETY_RULES}}。

## Example Tasks
- 範例 1：實作 {{EXAMPLE_ENDPOINT}} 端點，並補上單元測試。
- 範例 2：重構 {{EXAMPLE_SERVICE}} 服務，行為不變、測試保持綠燈。

# === 使用說明 ===
# 新專案先用範本 A 起步；當需要規範環境、測試、慣例與安全邊界時，升級到範本 B。
# 把 AGENTS.md 放在 repo 根目錄；多數 agent（含 OpenAI Codex）會自動讀取它。