OpenAI Codex 官方 AGENTS.md：大型專案怎麼寫給 AI 看的規則

# AGENTS.md

> 給 AI coding agent（Codex / Claude Code 等）讀的專案規則檔。放在 repo 根目錄（子目錄可放更貼近該層的覆寫版）。原則：寫成「明確、有立場、可機械執行」的條列，而不是抽象原則。

## Project Setup
- Toolchain / runtime: {{TOOLCHAIN}}（例：Node 20 + pnpm / Rust stable / Python 3.12）
- Required tools to install before starting: {{REQUIRED_TOOLS}}（例：`just`, `rg`, linter）
- DO NOT touch: {{DO_NOT_TOUCH}}（例：sandbox / 環境變數開關 / 生成檔；列出 agent 絕不能改的東西）

## Code Style
- Run `{{FORMAT_CMD}}` automatically after every change (e.g. `just fmt`, `npm run format`).
- Lint with `{{LINT_CMD}}`; fix all warnings before finishing.
- API design: prefer explicit enums/named methods over boolean or ambiguous optional params.
- Prefer private modules with explicit public exports; add doc comments to new public APIs.

## Testing
- Run `{{TEST_CMD}}` (NOT the raw test runner) — e.g. `just test`, `npm test`.
- Scope a single package: `{{TEST_PACKAGE_CMD}}`.
- After changes to {{CORE_AREAS}}, run the full suite.
- Test authoring: compare whole objects, not individual fields; don't write tests for static constants or removed logic.
- {{SNAPSHOT_RULE}}（若有快照測試：所有 UI/輸出變更都要附對應快照，並用 review→accept 流程）

## Module Size & Organization
- Target modules under {{SOFT_LOC}} LoC (excluding tests); split before {{HARD_LOC}} LoC.
- Don't grow large orchestration files; when extracting code, move its tests and docs together.

## Change Size Guidance
- General changes: max {{MAX_LINES}} lines per change.
- Complex logic: keep under {{COMPLEX_MAX_LINES}} lines; stage larger work into reviewable pieces.
- Build context incrementally; do not rewrite history.

## API / Naming Conventions（依專案調整或刪除）
- New surface goes in {{API_VERSION}} only; no additions to deprecated versions.
- Naming: `*Params` (requests), `*Response` (responses), `*Notification` (events).
- Serialization: {{SERIALIZATION_RULE}}（例：camelCase via serde rename / snake_case for config）.

## Breaking Changes — check impact on
- Public APIs / CLI params / config loading / session or state resumption.

## Commits & PRs
- {{COMMIT_CONVENTION}}（例：Conventional Commits；一個邏輯變更一個 commit）
- 完成前自我檢查：format ✅ / lint ✅ / test ✅ / 變更行數在上限內 ✅

# AGENTS.md

> 給 AI coding agent（Codex / Claude Code 等）讀的專案規則檔。放在 repo 根目錄（子目錄可放更貼近該層的覆寫版）。原則：寫成「明確、有立場、可機械執行」的條列，而不是抽象原則。

## Project Setup
- Toolchain / runtime: {{TOOLCHAIN}}（例：Node 20 + pnpm / Rust stable / Python 3.12）
- Required tools to install before starting: {{REQUIRED_TOOLS}}（例：`just`, `rg`, linter）
- DO NOT touch: {{DO_NOT_TOUCH}}（例：sandbox / 環境變數開關 / 生成檔；列出 agent 絕不能改的東西）

## Code Style
- Run `{{FORMAT_CMD}}` automatically after every change (e.g. `just fmt`, `npm run format`).
- Lint with `{{LINT_CMD}}`; fix all warnings before finishing.
- API design: prefer explicit enums/named methods over boolean or ambiguous optional params.
- Prefer private modules with explicit public exports; add doc comments to new public APIs.

## Testing
- Run `{{TEST_CMD}}` (NOT the raw test runner) — e.g. `just test`, `npm test`.
- Scope a single package: `{{TEST_PACKAGE_CMD}}`.
- After changes to {{CORE_AREAS}}, run the full suite.
- Test authoring: compare whole objects, not individual fields; don't write tests for static constants or removed logic.
- {{SNAPSHOT_RULE}}（若有快照測試：所有 UI/輸出變更都要附對應快照，並用 review→accept 流程）

## Module Size & Organization
- Target modules under {{SOFT_LOC}} LoC (excluding tests); split before {{HARD_LOC}} LoC.
- Don't grow large orchestration files; when extracting code, move its tests and docs together.

## Change Size Guidance
- General changes: max {{MAX_LINES}} lines per change.
- Complex logic: keep under {{COMPLEX_MAX_LINES}} lines; stage larger work into reviewable pieces.
- Build context incrementally; do not rewrite history.

## API / Naming Conventions（依專案調整或刪除）
- New surface goes in {{API_VERSION}} only; no additions to deprecated versions.
- Naming: `*Params` (requests), `*Response` (responses), `*Notification` (events).
- Serialization: {{SERIALIZATION_RULE}}（例：camelCase via serde rename / snake_case for config）.

## Breaking Changes — check impact on
- Public APIs / CLI params / config loading / session or state resumption.

## Commits & PRs
- {{COMMIT_CONVENTION}}（例：Conventional Commits；一個邏輯變更一個 commit）
- 完成前自我檢查：format ✅ / lint ✅ / test ✅ / 變更行數在上限內 ✅