这是一篇由原始材料转换而来的阅读页，保留了源文件的主要结构，并补充了可追溯的来源说明与链接。

AGENTS.md — OpenAI-style harness for Codex-first engineering

This file is intentionally short. It is a map, not the manual.

Goal: let a coding agent enter a repository, find the right context fast, make safe progress, and leave the system cleaner than it found it.

0) Core philosophy

1. The repo is the source of truth. If knowledge is not in the repository, assume the agent cannot rely on it.

2. AGENTS.md is a directory, not an encyclopedia. Keep this file short and stable. Put detailed knowledge in docs/ and plans/.

3. Plans are first-class artifacts. Complex work must be recorded in versioned plan files, not left in prompts or chat history.

4. Mechanize invariants. Important architectural and quality rules should be enforced with scripts, lint, CI, and structural tests.

5. Feedback loops beat intuition. Prefer workflows where the agent can verify behavior through scripts, browser automation, logs, metrics, traces, and smoke tests.

1) Required repository structure

At minimum, the repository should expose these entry points:

• AGENTS.md
• init.sh
• progress.md
• feature_list.json
• docs/
• plans/
• scripts/ or tools/

Suggested docs layout:

• docs/index.md — top-level map
• docs/architecture/ — layering, domains, invariants
• docs/product/ — user-facing behavior and requirements
• docs/runbooks/ — start, debug, deploy, rollback
• docs/quality/ — lint/test/CI expectations
• docs/debt/ — active technical debt and cleanup targets

Suggested plan layout:

• plans/active/
• plans/done/
• plans/templates/

2) Session startup protocol

Every coding session must begin with these steps:

1. Confirm location and current health

pwd
ls
git status
git log --oneline -20

2. Read the map and the latest handoff

sed -n '1,200p' AGENTS.md
sed -n '1,200p' progress.md || true
sed -n '1,200p' docs/index.md || true

3. Inspect active plans and unfinished features

find plans/active -maxdepth 2 -type f 2>/dev/null | sort
head -n 160 feature_list.json 2>/dev/null || true

4. Run the environment bootstrap and smoke test

bash ./init.sh

If init.sh fails, fix the baseline before starting new work.

3) How to choose work

Small work

Use a lightweight task note or progress.md update when the change is: - isolated - easy to verify - unlikely to span multiple sessions

Complex work

Create or update an execution plan in plans/active/ when the change involves: - multiple subsystems - architectural impact - migrations - UI + backend coordination - nontrivial rollback or verification logic

A plan should include: - objective - scope / non-goals - assumptions - constraints - execution steps - verification steps - rollback path - decisions log - current status

4) Implementation rules

1. Do one coherent increment per session.
2. Do not declare completion without verification.
3. Do not rely on unstored human knowledge. If a missing rule or decision matters, write it down in the repo.
4. Prefer existing scripts over ad hoc shell commands. If a command is likely to be repeated, add or improve a script.
5. When you discover a recurring failure mode, fix the harness, not only the symptom.

5) Verification hierarchy

Use the strongest practical verification available:

1. static checks / lint
2. unit and integration tests
3. smoke tests via init.sh
4. browser / UI verification
5. logs / metrics / traces for runtime confirmation

A feature should only move to passes: true after a suitable end-to-end validation path has passed.

6) End-of-session handoff

Before ending the session:

1. Update progress.md with: - goal - files changed - commands run - results - known issues / risks - next recommended step

2. Update any relevant plan in plans/active/

3. Update feature_list.json if and only if verification justifies it
4. Commit cleanly

git add -A
git commit -m "feat: <short summary>"
git status

7) Codex CLI launch patterns

Bootstrap a new repository harness

codex exec -m gpt-5.4 -C <REPO_DIR> --full-auto - <<'PROMPT'
You are bootstrapping an OpenAI-style coding harness for this repository.

Create or improve these artifacts:
- AGENTS.md (short map only)
- docs/index.md
- init.sh
- progress.md
- feature_list.json
- plans/active/
- plans/done/
- plans/templates/exec-plan.md

Do not implement product features yet.
Run init.sh once. If prerequisites are missing, document them precisely.
Commit the harness bootstrap as:
"chore: initialize codex harness"
PROMPT

Execute one planned increment

codex exec -m gpt-5.4 -C <REPO_DIR> --full-auto - <<'PROMPT'
You are the coding agent.

Process:
1) read AGENTS.md, progress.md, docs/index.md
2) inspect plans/active and feature_list.json
3) run bash ./init.sh
4) choose one coherent increment
5) implement and verify it
6) update progress.md and any active plan
7) only mark feature_list.json passes=true after verification
8) commit cleanly

If you discover missing repository knowledge, add it to docs rather than keeping it implicit.
PROMPT

Run a documentation gardening session

codex exec -m gpt-5.4 -C <REPO_DIR> --full-auto - <<'PROMPT'
You are the doc-gardening agent.

Audit docs for:
- stale statements
- missing cross-links
- mismatches between docs and code
- missing runbooks or architecture notes for frequently touched areas

Make only documentation / harness / linting improvements.
Commit with:
"docs: garden repository knowledge"
PROMPT