The AGENTS.md Starter Template: A Minimal File Any AI Agent Can Understand

## What it is / what pain point it solves AGENTS.md is an open standard — a plain Markdown guidance file placed at the root of a project for AI coding agents to read, functioning like a 'README written for machines.' The pain point: humans read READMEs, but AI agents need more direct operational instructions (which command to start with, how to test, what not to do). Centralizing conventions that would otherwise live in people's heads or in Slack into one file means the agent never has to guess or ask every time. ## Why this source is worth using This entry curates the AGENTS.md from the agents.md standard project's own repository. What makes it special is that it's inherently exemplary — a project promoting the standard naturally has a 'minimal but complete' AGENTS.md as its own showcase. It's much less sprawling than a large project's version, making it a great starting template for beginners — one glance and you understand what sections a basic AGENTS.md should have. As a cross-tool open format, AGENTS.md is actively read by Codex, Claude Code, and other agents — write one and it works everywhere. ## Key points covered in the original file - One core rule: during development, 'always use the dev server (npm run dev)' — don't run a production build inside an agent session, because building disables hot reload and slows down iteration. Condensed into one line: 'When in doubt, restart the dev server rather than running a production build.' - Dependency management: after adding/updating a package, sync the lockfile and restart the dev server so the framework picks up the new changes. - Code conventions: use TypeScript for new components, and keep styles co-located with components where possible. - A command table: mapping dev / lint / test / build to their respective commands — so the agent knows which command to run for which purpose. ## How to use it 1. Create AGENTS.md at the root of your repo. 2. Apply the template on the right, replacing {{DEV_CMD}}, {{LINT_CMD}}, {{TEST_CMD}}, {{BUILD_CMD}} with your project's actual commands. 3. Spell out clearly what the agent should normally do and what it should absolutely never do (this template's example: use the dev server, don't build). 4. From then on, agents like Codex and Claude Code will automatically read it when they enter the project. ## When to use it The 'first agent document' for any new project. Start with this minimal version, and as the project grows and conventions multiply, add testing discipline, module size limits, API naming rules, etc. (see another entry curating openai/codex's official, more advanced AGENTS.md). Source: the AGENTS.md file in the agentsmd/agents.md repository (Copyright © 2025 OpenAI, MIT License) — this entry is a Traditional Chinese rewrite/summary; see the source link for the original.

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

# AGENTS.md

> 給 AI coding agent（Codex / Claude Code 等）讀的專案指引。目標：讓 agent 不靠猜就知道「平常怎麼開發、怎麼驗證、有哪些指令」。

## Dev environment（最重要的一條）
- Always use `{{DEV_CMD}}` while iterating (e.g. `npm run dev` / `pnpm dev`).
- Do NOT run production builds during agent sessions — they disable hot reload and slow iteration down.
- When in doubt, restart the dev server rather than running a production build.

## Dependencies
- After adding or updating packages, sync the lockfile and restart the dev server so the framework picks up the change.

## Code style
- Prefer {{LANGUAGE}} for new components (e.g. TypeScript).
- Co-locate styles with their component when practical.
- {{EXTRA_STYLE_RULES}}（其他你想讓 agent 遵守的風格規則，沒有可刪）

## Commands
| 目的 | 指令 |
| --- | --- |
| 開發（agent 平常用這個） | `{{DEV_CMD}}` |
| Lint | `{{LINT_CMD}}` |
| 測試 | `{{TEST_CMD}}` |
| 正式打包（agent session 外才用） | `{{BUILD_CMD}}` |

## Notes for the agent
- {{PROJECT_SPECIFIC_NOTE}}（任何專案專屬的注意事項，例：環境變數放哪、哪些目錄別動）