用 Codex 迭代开发工作流

引言

Codex 提供的能力很广，但很难知道该从哪里开始把它接入自己的工作流。本文展示一种实用方法：一边把 Codex 接入开发流程，一边做迭代改进，从而持续、更有效地利用它的能力。

AGENTS.md 文件是可选的，但 Codex 会识别它。本文提到的其他文件是推荐的工作流约定，不是 Codex 必需的文件。请根据项目实际情况调整结构。

下面是一个简单待办事项应用完成后的目录结构。context/ 目录中的文件在开发的各个阶段生成，保存该阶段特有的上下文记录。

示例目录结构

.
├── .gitignore
├── AGENTS.md
├── GOALS.md
├── PLANS.md
├── PROMPTS.md
├── README.md
└── harness
    ├── build
    │   ├── phase-00-repository-foundation.md
    │   ├── phase-01-create-list.md
    │   ├── phase-02-update-complete-delete.md
    │   └── phase-03-demo-verification.md
    ├── build-log.md
    ├── code_review
    │   └── .gitkeep
    └── context
        └── README.md

4 directories, 13 files

创建 harness 与构建阶段文件

智能体与计划

对于新项目，最好的起点是填写 AGENTS.md。只要它存在，Codex 就会在执行工作前把它当作持久的仓库指引来读取。对于需要长期执行的工作，这是一项可选的约定。一般来说，agents 文件应包含：

• 仓库的目标与高层摘要
• 编码约定
• 测试标准
• 相关的上下文文件
• 项目特有的行为
• 范围与边界

Codex 中的 /init 命令可以生成该文件，并会尝试根据从目录内容中收集到的上下文来填充它。

提示：记录团队知识 agents 文件很适合存放团队积累的知识。

对于计划执行，创建一份 PLANS.md 作为事实来源，是一项有用但可选的约定。除了计划目的，这份文件还应包含项目路线图。虽然这些不是 Codex 要求的属性，但它们可以用来为每个构建阶段生成单独的文件。

提示：构建文件的大小 对于偏好长时间运行任务的团队，PLANS.md 可以更大，包含关于重要决策与验收标准的详细内容。 创建更小的构建文件不仅能提高可读性，也便于人工把关，手动审查代码质量与其他产出。

Harness 文件

除了 agents 与 plans 文件，还可以创建单独的文件来指定期望结果、成功条件与边界（GOALS.md），以及启动计划工作的指令（PROMPTS.md）。这些文件可以手写，也可以用下面这样的提示词从 agents 与 plans 文件派生：

生成 GOALS.md 与 PROMPTS.md

Read the applicable `AGENTS.md` files for this repository, starting at the
repository root and including any instructions that apply to the current
directory. If `PLANS.md` exists, read it as well.

Using those sources, create or conservatively update only these files:

- `GOALS.md`
- `PROMPTS.md`

Before writing, briefly summarize:

1. The source files you found
2. The project outcomes and constraints you inferred
3. Any assumptions caused by missing or ambiguous information

Use the following ownership boundaries:

## `GOALS.md`

Document what the project is trying to achieve. Include:

- Project purpose
- Desired outcomes
- Success conditions
- Scope
- Non-goals
- Technical and operational constraints
- Security, reliability, and recovery expectations when supported by the sources
- Known unknowns or decisions that still require human input

Keep goals outcome-oriented. Do not copy implementation procedures, reusable
prompts, or progress updates into this file. Do not claim capabilities,
deadlines, guarantees, or requirements that are not supported by the source
material.

## `PROMPTS.md`

Provide reusable prompts for initiating and advancing the planned work. Include:

- A repository-orientation prompt
- A planning or phase-preparation prompt
- A prompt for executing one approved phase
- A verification and evidence-gathering prompt
- A review or remediation prompt
- A phase-completion and handoff prompt

Each prompt should:

- Tell Codex which repository files to read
- Reference the relevant goal or plan instead of duplicating it
- Define the immediate scope and explicit non-goals
- Require a read-only preflight before implementation
- Require an approval summary before repository writes
- Use red, green, refactor, and verification where appropriate
- Require observed test and validation evidence
- Keep commits, pushes, deployments, credentials, and external writes behind
  separate explicit approval
- Stop after the selected phase rather than beginning the next one automatically

If `PLANS.md` does not exist:

- Derive only high-level goals supported by `AGENTS.md`
- Do not invent a roadmap, phases, architecture, or product requirements
- Use clearly marked placeholders where planning input is required
- Make the prompts request an explicit plan or phase before implementation

Preserve existing repository terminology and filename capitalization. Keep both
documents concise and avoid repeating information already owned by
`AGENTS.md` or `PLANS.md`.

Do not modify application code, tests, dependencies, configuration, existing
planning files, or any other files.

After writing:

1. Review both files for contradictions and duplicated ownership
2. Confirm that every substantive claim is grounded in `AGENTS.md` or
   `PLANS.md`, or is clearly labeled as an assumption
3. Run `git diff --check`
4. Report the files changed, assumptions made, and any unresolved questions

构建阶段文件

当 harness 用来提供上下文的文件生成后，下一步是把每个构建拆成单独的文件，以明确：

• 每一步的目的
• 需要哪些文件提供额外上下文
• 验收标准
• 边界

为了方便查找，建议把这些文件放在项目根目录下手动创建的 harness/build/ 文件夹中，通常采用 <阶段编号>-<阶段标题>.md 的格式。在每个阶段开始时，把对应文件连同 harness 上下文文件中的提示词与目标一起交给 Codex。这有助于防止智能体偏离方向，并形成清晰、由人把关的开发历史；再结合版本控制，就能留下易于阅读的审计轨迹，供日后调试使用。

生成构建阶段文件

Perform a read-only discovery pass of this repository.

Read the applicable repository instructions and planning sources, including:

- `AGENTS.md`
- `PLANS.md`, if present
- `GOALS.md`, if present
- `PROMPTS.md`, if present
- `harness/build-log.md`, if present
- Existing files under `harness/build/`
- Relevant application manifests, tests, and verification commands

Use the live repository as the source of truth. Do not rely on assumptions from
other projects.

Your task is to create the planned phase files under `harness/build/`.

## Before writing

Identify:

1. The source files you found
2. The repository’s purpose and current state
3. The planned phases and their dependencies
4. The exact build files you propose creating
5. Any missing, ambiguous, or contradictory requirements
6. The acceptance criteria for this planning task

If the source files do not establish a clear phase sequence, stop and propose a
phase breakdown for human review. Do not invent and write a roadmap without
approval.

Before creating files, present the proposed scope and exact paths and wait for
explicit confirmation.

## Build-file ownership

Each build file describes one bounded implementation phase. It is a plan, not
evidence that the work has already been completed.

Use the phase numbers, names, ordering, and terminology established by the
repository. Follow an existing build-file template when one is present.

Each phase file should contain:

- Phase number and descriptive title
- Status, initially `Not started`
- Source inputs
- Objective
- In-scope work
- Explicit non-goals
- Dependencies and prerequisites
- Expected files or components affected
- Decisions requiring human input
- Approval gate
- Red, green, refactor, and verification plan
- Focused and broader verification commands
- Security, privacy, reliability, observability, and recovery considerations
  when relevant to the phase
- Acceptance criteria
- Evidence that must be recorded before the phase can be considered complete
- Handoff or stop condition

## Planning requirements

For every phase:

1. Keep the scope small enough to implement and verify independently.
2. Preserve dependency order and do not move later work into earlier phases.
3. Define observable acceptance criteria rather than subjective completion
   statements.
4. Include the smallest meaningful failing test or check for the red step.
5. Describe the minimum implementation needed for the green step.
6. Allow refactoring only when it preserves the approved behavior and scope.
7. Name the actual verification commands when they can be established from the
   repository.
8. Mark unknown commands or requirements as unresolved instead of inventing
   them.
9. Identify credentials, external systems, infrastructure changes, deployments,
   commits, and pushes that require separate authorization.
10. Do not claim that tests, recovery procedures, or integrations have passed
    unless they have actually been run during a separately approved
    implementation phase.

## Scope restrictions

Create or update only the explicitly approved files under:

`harness/build/`

Do not create or modify:

- Application code
- Tests
- Dependencies
- Package manifests
- Infrastructure or deployment configuration
- `AGENTS.md`
- `PLANS.md`
- `GOALS.md`
- `PROMPTS.md`
- Context files
- Execution or build logs
- Code-review artifacts
- README files
- Git branches, commits, or remote state

Do not begin implementing any phase.

If a proposed build file already exists, inspect it and describe the intended
changes before modifying it. Preserve useful existing content and do not
overwrite recorded decisions or evidence.

## After writing

1. Confirm that only approved `harness/build/` files changed.
2. Check that every phase traces back to the repository’s source documents.
3. Check for duplicated, missing, or incorrectly ordered scope.
4. Confirm that every phase includes an approval gate, acceptance criteria, and
   verification plan.
5. Run `git diff --check`.
6. Report:
   - Files created or updated
   - Phase sequence
   - Validation performed
   - Assumptions and unresolved questions
   - The approval needed before beginning the first phase

上下文文件

除了开发框架文件，还要记录每个阶段中做出的、会实质影响项目的会话级决策。

把下面这样的提示词加入 AGENTS.md，可以指示 Codex 记录相关上下文，供以后复用。阶段上下文存放为 harness/context/phase-<NN>-<phase-slug>-context.md。

使用 AGENTS.md 记录构建阶段上下文

## Phase context requirements

For each approved implementation phase, maintain one phase-specific context file:

`harness/context/phase-<NN>-<phase-slug>-context.md`

Create the context file only when the phase begins and after any required
approval. Read the applicable repository instructions, goal, prompt, build
file, prior context, and build-log evidence before recording
new context.

### Materiality test

Record information only when omitting it could reasonably:

- Change the approved scope or implementation approach
- Cause a future phase to repeat discovery or make a different decision
- Affect an interface, dependency, invariant, or ownership boundary
- Change acceptance criteria or the required verification
- Affect security, privacy, reliability, observability, rollback, or recovery
- Hide a blocker, unresolved assumption, accepted limitation, or required
  follow-up

If the information would not affect future work, verification, operations, or
decision-making, do not add it to the context file.

### Capture

Record material:

- User decisions and clarifications
- Scope changes and explicit non-goals
- Assumptions that influenced implementation
- Architectural or implementation decisions and their rationale
- Relevant component, interface, dependency, and ownership boundaries
- Existing behavior or invariants that must be preserved
- Security, privacy, operational, and recovery constraints
- Verification limitations or unavailable evidence
- Blockers and unresolved questions
- Findings that must inform a later phase
- Superseded decisions, including what replaced them and why

For each entry, include enough provenance to recover the reasoning. Reference
the relevant file, command, test result, issue, review finding, or user decision
when available.

### Do not capture

Do not use context files as transcripts, scratchpads, or progress logs. Exclude:

- Routine command output
- Step-by-step narration
- Temporary dead ends that had no lasting effect
- Facts already owned by another canonical file
- Full copies of plans, prompts, test output, or source code
- Routine progress or completion status
- Speculation presented as fact
- Credentials, tokens, secrets, or sensitive values

Link to canonical sources instead of duplicating their contents.

### Source-of-truth boundaries

- The phase build file owns approved scope, non-goals, acceptance criteria, and
  the planned verification.
- The phase context file owns material discoveries, decisions, constraints, and
  unresolved matters needed by future work.
- `harness/build-log.md` owns implementation progress and observed verification
  evidence.
- Code-review artifacts own review findings and sign-off status.

Do not copy information between these files unless a short summary is necessary
to explain a material decision.

### Update and handoff

Update the context file when a material decision or discovery occurs and review
it before closing the phase. Before handoff:

1. Remove non-material narration and duplicated information.
2. Confirm that material decisions include their rationale and provenance.
3. Mark assumptions and unresolved questions explicitly.
4. Confirm that evidence is linked rather than claimed without support.
5. Record downstream implications for later phases.
6. Do not mark the phase complete solely because the context file is complete.

构建日志

名为 harness/build-log.md 的文件是项目进度的事实来源。它既方便人阅读，也主要面向 Codex 使用，还可以用来生成面向用户的变更日志与其他文档。

可以把下面这样的提示词加入 agents 文件，确保每个阶段完成后都一致地更新构建日志。

用 build-log.md 跟踪进度

# Build Log Instructions
At the end of each phase, prior to committing work, your task is to create or update only:

`harness/build-log.md`

The build log is the source of truth for observed implementation progress and
verification evidence. It must describe what actually happened, not what the
plan predicts will happen.

## Before writing

Summarize:

1. The selected phase
2. Its current recorded status
3. The sources and evidence you inspected
4. The log entries or status changes you propose
5. Any conflicting, missing, or unverified information

Wait for explicit confirmation before creating or updating the build log when
repository instructions require approval for documentation writes.

## Initialize the log

If `harness/build-log.md` does not exist, create it with:

1. A short statement of purpose
2. A phase summary table
3. An append-only activity section

Build the phase summary table from the approved files under `harness/build/`.
Initialize phases as `Not started` unless repository evidence supports another
status.

Use only these statuses unless the repository defines its own:

- `Not started`
- `In progress`
- `Blocked`
- `Complete`

Do not infer completion from the existence of code, a passing focused test, or
a prior conversation.

## Phase summary

Maintain a concise summary table containing:

| Phase | Status | Branch | Started | Completed | Evidence | Blockers |
|---|---|---|---|---|---|---|

The table is a current summary. Detailed history belongs in append-only activity
entries.

Only mark a phase `Complete` when:

- Its approved acceptance criteria are satisfied
- Required tests and verification have actually run and passed
- Required review findings are resolved or explicitly accepted
- Operational, security, recovery, and cleanup requirements are satisfied when
  applicable
- Remaining limitations are recorded
- Repository-specific completion requirements are met

If any required condition lacks evidence, keep the phase `In progress` or
`Blocked`.

## Append-only activity entries

Append an entry whenever a material phase event occurs, including:

- Phase authorization
- Work beginning
- A red test or check producing the expected failure
- The focused check passing after implementation
- A material refactor or an explicit decision not to refactor
- Broader verification
- A material scope change
- A blocker
- A review finding or remediation
- Acceptance or rejection of a limitation
- Phase completion

Use this structure:

## <timestamp> — Phase <NN>: <event>

- **Status:** `<previous status>` → `<new status>`
- **Branch:** `<observed branch>`
- **Authorized scope:** Brief summary or link to the phase build file
- **Changes:** Material files, components, or behavior changed
- **Red:** Exact check and observed expected failure, or `Not applicable` with
  justification
- **Green:** Exact focused check and observed result
- **Refactor:** Material refactor and repeated checks, or the reason no
  refactor was needed
- **Verification:** Exact commands or procedures actually run and their results
- **Review:** Findings, remediation, and sign-off state when required
- **Operational evidence:** Relevant security, observability, rollback,
  recovery, or cleanup evidence
- **Limitations:** Untested areas, accepted risks, or incomplete evidence
- **Blockers:** Current blockers or `None`
- **Next action:** The next approved action; do not authorize it implicitly
- **Evidence references:** Paths to context files, review artifacts, logs,
  commits, or other durable evidence

Use an unambiguous timestamp including the timezone.

## Evidence requirements

- Record exact commands and concise pass/fail results.
- Distinguish observed evidence from reported or historical evidence.
- Never claim that a test, integration, recovery procedure, or external check
  passed unless it was actually run and the result was observed.
- Never convert planned commands from a build file into passing evidence.
- Record skipped and unavailable checks explicitly, including the reason.
- Link to large outputs or artifacts instead of copying them into the log.
- Do not include credentials, tokens, secrets, sensitive values, or unnecessary
  personal information.
- Do not copy full context files, build plans, code diffs, or command output
  into the build log.
- If evidence conflicts, preserve both observations and mark the phase
  `Blocked` until the conflict is resolved.

## History and corrections

Treat activity entries as append-only.

Do not silently rewrite prior evidence or remove failed attempts. If an earlier
entry is incorrect:

1. Append a correction
2. Identify the entry being corrected
3. Explain what changed
4. Update the summary table to reflect the current supported state

Routine typo fixes that do not change meaning may be corrected in place.

## Source-of-truth boundaries

- `PLANS.md` owns the planned phase sequence.
- `harness/build/<phase>.md` owns phase scope, non-goals, acceptance criteria,
  and planned verification.
- `harness/context/` owns material discoveries, decisions, constraints, and
  unresolved questions.
- `harness/build-log.md` owns observed progress and verification evidence.
- Review artifacts own detailed findings and sign-off.

Reference those sources instead of duplicating them.

## Scope restrictions

Do not:

- Implement or modify application code
- Modify tests or configuration
- Create phase context
- Change build files or the execution plan
- Change Git branches
- Commit or push
- Start the next phase
- Mark a phase complete without sufficient evidence

If the evidence indicates that another file needs an update, report it as a
follow-up rather than modifying it.

## After writing

1. Confirm that the logging task changed only `harness/build-log.md` and
   preserved any pre-existing phase implementation, test, or other worktree
   changes.
2. Confirm that every status transition has supporting evidence.
3. Confirm that planned work is not represented as completed work.
4. Confirm that failures, skipped checks, and limitations remain visible.
5. Run `git diff --check`.
6. Report:
   - The phase and status recorded
   - The entries appended
   - The evidence used
   - Remaining blockers or limitations
   - Any separate approval required for the next action

用技能自动化

考虑到每个提示词的篇幅与涉及的文件数量，这种手工流程显然会变得笨重、容易出错且难以预测。为了让这类工作可复用、更一致，Codex 提供了技能（skills），用来创建可适用于任意规模项目的工作流。

使用 Skill Creator 技能 配合下面的提示词，创建一个可复用的 harness 编写技能。

创建 $harness-author 技能

Use `$skill-creator` to create a reusable Codex skill named `harness-author`.

The skill should help Codex create, review, and improve a right-sized
repository engineering harness without beginning implementation unless the
user explicitly requests and separately approves it.

## Destination

Before writing, determine where the skill should be installed.

Default to:

`${CODEX_HOME:-$HOME/.codex}/skills/harness-author`

If the destination is ambiguous or an existing `harness-author` skill is
present, report the exact path and ask whether to update it or choose another
name. Do not overwrite an existing skill without explicit approval.

## Read-only discovery

Before creating the skill:

1. Read the applicable repository `AGENTS.md` files.
2. Inspect existing harness examples and conventions in the current repository.
3. Read `PLANS.md`, `GOALS.md`, and `PROMPTS.md` when present.
4. Inspect existing `harness/` files without modifying them.
5. Identify concrete requests that should and should not trigger the skill.
6. Determine which behavior belongs in `SKILL.md`, reference files, scripts,
   and tests.
7. Read the `$skill-creator` instructions and required references completely.

Do not infer that one repository’s harness structure is mandatory for every
project.

## Before writing

Present:

- The proposed skill path
- The triggering description
- The files and resources to be created
- The behavioral scope
- Explicit non-goals
- The validator and test plan
- The acceptance criteria

Wait for confirmation before creating or modifying the skill.

## Triggering behavior

The skill should trigger when a user asks Codex to:

- Create or review a repository engineering harness
- Create durable repository instructions
- Convert goals or plans into phased build files
- Define acceptance criteria and approval gates
- Create or streamline execution and build logs
- Establish test-driven phase plans
- Separate planning, implementation, context, and evidence
- Improve an existing harness after observing workflow failures

The description should also make clear that requests containing terms such as
“harness-only,” “planning-only,” “just the build files,” or “only these files”
must not authorize application implementation.

## Core behavior

The skill must instruct Codex to:

1. Read applicable repository instructions and inspect the live repository
   before designing the harness.
2. Identify the authoritative source for goals, plans, implementation
   contracts, phase status, context, review findings, and verification evidence.
3. Classify the repository shape and change risk.
4. Recommend the smallest useful harness for that repository.
5. Preserve existing architecture, naming, ownership, and operational
   safeguards.
6. Freeze the exact user-approved artifact list before writing.
7. Present scope, affected files, tests, acceptance criteria, risks, and
   approval gates before repository changes.
8. Keep planning and implementation as separately authorized activities.
9. Use red, green, refactor, and verification checkpoints in implementation
   plans when appropriate.
10. Define observable acceptance criteria and evidence requirements.
11. Record unknowns as unresolved rather than inventing requirements or proof.
12. Avoid duplicating facts across multiple harness files.
13. Preserve existing application files.
14. Require separate approval for credentials, external systems,
    infrastructure, branch changes, commits, pushes, and deployments.

## Artifact ownership

Teach the skill to distinguish these possible artifacts:

- `AGENTS.md`: durable repository instructions and working agreements
- `PLANS.md`: roadmap and planned phase sequence
- `GOALS.md`: outcomes, success conditions, scope, and non-goals
- `PROMPTS.md`: reusable workflow entry points
- `harness/build/<phase>.md`: approved scope and plan for one phase
- `harness/context/<phase>.md`: material discoveries, decisions, constraints,
  and unresolved questions for one phase
- `harness/build-log.md`: observed progress and verification evidence
- `harness/code_review/`: detailed review findings when required

These are optional conventions, not files Codex requires automatically. The
skill must extend existing repository conventions instead of creating every
artifact by default.

## Planning-only boundary

When the user requests only planning or harness artifacts:

- Create only the explicitly approved files.
- Do not create application code.
- Do not create tests for the application.
- Do not add dependencies or manifests.
- Do not create Docker, infrastructure, or deployment files.
- Do not create README files or review artifacts unless explicitly approved.
- Do not create phase context files before the corresponding phase begins
  unless the user explicitly requests them.
- Do not change Git state, commit, push, or access external systems.
- Describe future implementation and tests inside the plans only.
- Stop after validating and reporting the harness artifacts.

## Right-sizing

The skill should adapt its recommendations:

- For a minimal project, prefer existing documentation, tests, and a concise
  acceptance checklist.
- For an application, add phased planning and recovery guidance only when
  useful.
- For multiple services, capture ownership, contracts, dependency boundaries,
  degraded behavior, and integration verification.
- For a monorepo, combine root guidance with only the applicable package-level
  instructions.
- For high-risk changes, include security, authorization, rollback, recovery,
  failure modes, and independent verification regardless of repository size.

Do not impose enterprise process, mandatory reviewers, or extra documents when
the repository and risk do not justify them.

## Skill structure

Use `$skill-creator`’s initialization script rather than manually creating the
skill skeleton.

Create only resources that materially support the workflow. The likely
structure is:

harness-author/
├── SKILL.md
├── agents/
│   └── openai.yaml
├── references/
│   ├── project-profiles-and-templates.md
│   ├── source-of-truth-and-templates.md
│   ├── tdd-and-verification.md
│   └── reliability-and-tradeoffs.md
└── scripts/
    ├── validate_harness.py
    └── test_validate_harness.py

Do not create a README, changelog, installation guide, or other auxiliary
documentation.

Keep `SKILL.md` concise and procedural. Move detailed templates, matrices, and
examples into the directly linked reference files. Avoid duplicating content
between `SKILL.md` and its references.

Generate `agents/openai.yaml` using the `$skill-creator` tooling. Read the
required `openai.yaml` reference before generating:

- `display_name`
- `short_description`
- `default_prompt`

Do not add optional branding fields unless the user supplies them.

## Deterministic validator

Create a standard-library validator that can inspect a repository and validate
a proposed harness without modifying files or printing source contents.

It should support:

- Repository and optional target paths
- Project-shape and risk assessment
- A `harness-only` intent
- Repeated proposed-path arguments
- Repeated explicitly allowed-path arguments
- JSON output
- Strict mode for blocking findings

It should reject:

- Absolute paths
- Path traversal
- Proposed application scaffolding during harness-only requests
- Files outside the approved artifact set
- Context, review, or implementation artifacts that were not explicitly
  approved
- Missing approval, acceptance, or verification sections when required
- Claims of completed verification without evidence

Keep the validator advisory for repositories that do not use this harness
structure. It must not make network calls, access credentials, change Git
state, or modify repository files.

## Tests

Write and run tests for at least these cases:

1. A valid minimal harness-only request
2. An explicitly approved custom Markdown artifact
3. Rejection of application code during a planning-only request
4. Rejection of dependencies, manifests, Docker, and infrastructure files
5. Rejection of unapproved context and review artifacts
6. Safe normalization of relative paths
7. Rejection of absolute paths and traversal
8. Preservation of exact filename capitalization
9. A small repository that should not receive an oversized harness
10. A high-risk project that requires security and recovery coverage
11. JSON output and strict-mode behavior
12. An existing repository whose conventions should be preserved

Run added scripts and tests directly and report their observed results.

## Validation

After implementation:

1. Run the validator’s test suite.
2. Run `$skill-creator`’s `quick_validate.py` on the completed skill.
3. Confirm the YAML frontmatter contains only `name` and `description`.
4. Confirm the skill name uses lowercase hyphenated form.
5. Confirm `agents/openai.yaml` agrees with `SKILL.md`.
6. Inspect the final file list for unnecessary files.
7. Inspect the diff for accidental changes outside the approved destination.

If forward-testing would be useful, propose realistic test prompts and request
approval before launching subagents or modifying external repositories.

## Acceptance criteria

The skill is complete only when:

- It triggers for repository-harness authoring and review requests.
- It right-sizes the harness to the repository and risk.
- It preserves local repository conventions and sources of truth.
- A harness-only request cannot silently create implementation artifacts.
- Phase context remains session-created unless separately approved.
- Plans include meaningful acceptance and verification requirements.
- The validator and its tests pass.
- The skill passes `quick_validate.py`.
- No files outside the approved skill destination were changed.
- All limitations and untested behavior are reported.

Finish by reporting:

- Skill location
- Files created or changed
- Triggering description
- Validator behavior
- Tests and validation results
- Forward-testing not performed
- Remaining assumptions or limitations

提示：识别可重复的工作 几乎任何事都可以做成技能，但好的技能通常面向高频使用。日常工作中可能遇到的技能示例包括： - 提交代码改动、推送到远端并创建拉取请求 - 监视远端最新变更合并，然后准备下一个功能分支 - 从构建日志识别当前阶段，加载该阶段的目标与提示词，总结目的与验收标准，然后等待人工把关。

技能调优

技能在创建后可能不会完全按预期工作。例如，当要求创建 harness 上下文与构建阶段文件时，$harness-author 技能提出了下面的文件列表，却漏掉了 PLANS.md 与 harness/build-log.md：

...
 I propose creating the following files:

  - harness/build/00_repository_foundation.md
  - harness/build/01_sqlite_core.md
  - harness/build/02_add_and_list_cli.md
  - harness/build/03_interactive_completion.md
  - harness/build/04_hardening_and_verification.md
  - harness/build/05_documentation_and_handoff.md
  - harness/context/README.md
  - harness/context/00_repository_foundation_context.md
  ...

遇到这种情况，应在批准任何改动前修正提议的范围：

  Revise the proposed harness-only scope before writing.

Include these missing artifacts:

- PLANS.md: the ordered phase execution plan.
- harness/build-log.md: observed implementation progress and verification evidence.

Do not create a phase-specific context file until that phase begins and has
received the required approval. Include harness/context/README.md only if it
is explicitly approved as an exception to the standard harness-only allowlist.

Check the proposed artifact list for both missing required files and
unapproved additional files. Present the revised exact file list, explain
the ownership of each artifact, and wait for approval before writing.

应用修正后，Codex 会提出符合预期的 harness 文件：

 I propose creating the following files:

  - PLANS.md
  - harness/build-log.md
  - harness/build/00_repository_foundation.md
  - harness/build/01_sqlite_core.md
  - harness/build/02_add_and_list_cli.md
  - harness/build/03_interactive_completion.md
  - harness/build/04_hardening_and_verification.md
  - harness/build/05_documentation_and_handoff.md
  ...

回顾

现在整套结构已经为开始开发搭好，但要记住这只是起点。当项目按照 agents 文件中的标准完成，并且改动已提交到版本控制后，就该用 Codex 回头看看：过程中学到了什么，以及如何为后续改进做优化。

下面这段提示词可以让 Codex 生成一份回顾。

生成回顾

Use `$skill-creator` to conduct an evidence-backed postmortem of the completed
development workflow.

The goals are to:

1. Understand what worked and what created friction
2. Improve the existing harness-authoring skill
3. Identify missing reusable skills without creating overlapping skill sprawl
4. Improve repository instructions, harness artifacts, validators, and process
5. Convert verified workflow failures into regression tests or enforceable
   safeguards where appropriate

Do not modify any repository, harness, or skill files during the initial
postmortem.

## Read-only discovery

Read the applicable sources, including:

- Global and repository `AGENTS.md` files
- `PLANS.md`, `GOALS.md`, and `PROMPTS.md`, when present
- `harness/build-log.md`
- Applicable files under `harness/build/`
- Applicable files under `harness/context/`
- Code-review and postmortem artifacts
- Relevant implementation diffs
- Test and verification results
- Current Git branch and working-tree state
- User corrections, approval decisions, and accepted limitations
- The installed `harness-author` skill
- Other skills invoked during the workflow
- Their scripts, references, metadata, and tests
- Existing skills that could already own an identified procedure

Use current files and observed evidence as the source of truth. Do not treat
plans, intended behavior, prior conversations, or unverified reports as proof
of what occurred.

Do not access credentials, production systems, external services, or remote Git
state unless separately authorized.

## Reconstruct the intended workflow

Document:

- The intended sequence of phases
- The ownership of each harness artifact
- The expected approval gates
- The planned red, green, refactor, and verification checkpoints
- The expected review and handoff process
- Which skills should have triggered and what each was expected to own
- The expected boundaries around context, evidence, commits, pushes,
  deployments, credentials, and external writes

Distinguish required repository behavior from optional workflow conventions.

## Reconstruct what actually happened

Using observed evidence, identify:

- Work completed
- Commands and checks actually run
- Approval gates honored, missed, or ambiguous
- Scope changes
- Repeated discovery or duplicated work
- Incorrect assumptions
- Agent drift or overbuilding
- Missing or excessive context
- Misleading status or unsupported completion claims
- Manual interventions
- Review findings and remediation
- Failed, skipped, or unavailable verification
- Recovery or rollback issues
- User corrections
- Work that succeeded because of the harness or a skill
- Work that succeeded despite gaps in the process

Do not manufacture a root cause when evidence supports only a symptom or
correlation.

## Analyze each material event

For every material success, failure, or friction point, record:

| Field | Meaning |
|---|---|
| Event | What happened |
| Expected behavior | What should have happened |
| Observed evidence | What proves the event occurred |
| Impact | Effect on scope, quality, safety, time, or confidence |
| Contributing conditions | Evidence-supported factors |
| Current safeguard | Existing instruction, skill, test, or approval gate |
| Safeguard result | Worked, failed, missing, ambiguous, or bypassed |
| Generalizability | One-off, repository-specific, or reusable |
| Recommended owner | Where an improvement should live |
| Proposed validation | How the improvement would be tested |

Use a blameless framing. Focus on workflow design, missing information,
ambiguous ownership, and insufficient validation rather than assigning personal
fault.

## Apply a materiality test

Include an event only when it materially affected or could reasonably affect:

- Approved scope
- Implementation correctness
- Verification confidence
- Security or privacy
- Reliability, observability, rollback, or recovery
- Human approval or review
- Future phase decisions
- Repeated effort
- The ability to reproduce or audit the work

Do not fill the postmortem with harmless typos, routine command failures, or
temporary exploration that had no lasting impact.

## Classify improvement ownership

Assign every recommendation to exactly one primary owner.

### Repository instructions

Use `AGENTS.md` when the lesson is a durable, repository-specific convention,
constraint, command, or approval rule.

### Project harness

Use a goal, plan, build file, context file, execution tracker, build log, or
review artifact when the lesson applies only to this project or phase.

### Existing skill instructions

Update an existing skill when the lesson changes a reusable procedure,
triggering condition, safety boundary, or decision rule.

### Existing skill reference

Update a reference when the lesson adds detailed guidance, examples, matrices,
or variants that do not belong in the core `SKILL.md`.

### Existing skill script or validator

Use deterministic code when the condition can be checked mechanically and a
miss would be costly or repeatedly error-prone.

### Regression test

Add a regression test when the failure is reproducible and the expected
behavior can be asserted reliably.

### New skill

Recommend a new skill only when all of the following are true:

- The task has a distinct user intent and triggering vocabulary
- It represents a reusable multi-step procedure
- It will recur across repositories or phases
- It has a clear owner and bounded responsibility
- Existing skills cannot own it cleanly
- Creating it reduces complexity rather than redistributing duplication
- Its success can be validated independently

Do not recommend a new skill for a single rule, one repository’s convention,
a one-time incident, or functionality already owned by another skill.

### No process change

Choose no change when the event was non-material, adequately handled, or too
specific to justify permanent workflow complexity.

## Evaluate existing skill quality

For each skill used, assess:

- Did its description trigger for the right requests?
- Did it fail to trigger when it should have?
- Did it trigger too broadly?
- Did `SKILL.md` contain only essential procedural guidance?
- Were detailed instructions routed to the correct references?
- Were applicable references actually loaded?
- Did scripts enforce fragile or safety-critical behavior?
- Were script failures handled safely?
- Were approval boundaries explicit?
- Did the skill preserve repository-specific conventions?
- Did it create files or process that the repository did not need?
- Did it confuse plans with observed evidence?
- Did it overfit to a previous project?
- Did its UI metadata remain consistent with its behavior?
- Are new regression tests needed?

Prefer tightening an existing skill over creating another skill when ownership
is already clear.

## Identify process improvements

Evaluate the end-to-end process separately from individual skills:

- Repository orientation
- Source-of-truth ownership
- Harness generation
- Phase selection
- Context capture
- Approval packets
- Red, green, refactor, and verification
- Evidence recording
- Independent review
- Remediation
- Phase completion
- Commit and push approval
- Post-merge branch preparation
- Cross-phase handoff
- Postmortem timing

For every proposed process change, state:

- The problem it solves
- Its intended owner
- Whether it is advisory or mechanically enforced
- Its cost or added process burden
- The smallest useful change
- How to validate that it improved the workflow

Avoid adding process solely to make the harness look comprehensive.

## Produce the read-only postmortem

Return:

### Executive summary

A concise assessment of the workflow’s effectiveness and the most important
improvement opportunity.

### What worked

Evidence-backed practices and safeguards worth preserving.

### What created friction

Material problems, their impact, and their evidence.

### Existing skill improvements

For each proposed change:

- Skill name and path
- Trigger, instruction, reference, script, metadata, or test affected
- Evidence supporting the change
- Proposed behavior
- Risk of overfitting
- Validation required

### New skill candidates

For each candidate:

- Proposed lowercase hyphenated name
- Distinct triggering requests
- Responsibility and explicit non-goals
- Why an existing skill cannot own it
- Likely files or resources
- Concrete example requests
- Validation and forward-testing plan
- Priority: now, later, or reject

Include rejected skill candidates and explain which existing owner should
absorb the behavior.

### Harness and repository improvements

Changes that belong in `AGENTS.md`, planning files, context rules, logs,
validators, or review requirements.

### Prioritized improvement backlog

Group recommendations as:

- P0: Unsafe or materially incorrect workflow behavior
- P1: Repeated failures, approval gaps, or misleading evidence
- P2: Meaningful efficiency or clarity improvements
- P3: Optional polish

For each item, include effort, expected value, owner, and validation.

### Unresolved questions

Evidence gaps or decisions that require human input.

## Approval gate

After presenting the postmortem, stop.

Do not:

- Modify an existing skill
- Create a new skill
- Change repository instructions
- Change harness files
- Add scripts or tests
- Launch forward-testing
- Create commits or push changes

Request separate approval for:

1. Repository or harness changes
2. Changes to each existing skill
3. Creation of each new skill
4. Forward-testing
5. Commits or pushes

## Implement approved improvements

Only after explicit approval, use `$skill-creator` for skill changes.

For each approved skill change:

1. Confirm the exact skill path and affected files.
2. Add a failing regression test when the behavior is mechanically testable.
3. Make the smallest change that addresses the evidence-backed failure.
4. Keep `SKILL.md` concise and move detailed material into directly linked
   references.
5. Update scripts only when deterministic enforcement is justified.
6. Run the relevant script tests.
7. Run `$skill-creator`’s `quick_validate.py`.
8. Regenerate `agents/openai.yaml` only when its interface metadata is stale.
9. Inspect the final diff for unrelated changes.
10. Report observed results and remaining limitations.

For each approved new skill:

1. Confirm its distinct trigger and ownership boundary.
2. Confirm the installation destination.
3. Initialize it using `$skill-creator`’s `init_skill.py`.
4. Create only necessary resources.
5. Add and run relevant tests.
6. Run `quick_validate.py`.
7. Verify that it does not duplicate or conflict with existing skills.

## Forward-testing

When forward-testing is approved:

- Use fresh, independent contexts
- Provide realistic requests and raw artifacts
- Do not reveal the expected answer or suspected defect
- Test both positive and negative triggering cases
- Check for scope expansion and unsafe writes
- Remove or isolate generated test artifacts between runs
- Compare observed behavior with explicit acceptance criteria
- Feed verified failures back into instructions, validators, or regression tests

Do not declare the workflow improved solely because the skill passes structural
validation. Require evidence from realistic use.

## Completion criteria

The postmortem cycle is complete only when:

- Material events are supported by evidence
- Improvements have a clear owner
- Existing skills are preferred over unnecessary new skills
- Approved changes have regression coverage where practical
- Skill and script validation passes
- Forward-testing results are recorded when performed
- Repository-specific lessons remain in the repository
- Reusable lessons are encoded in the appropriate skill
- Remaining limitations and rejected recommendations are documented
- No unapproved files, external systems, commits, or pushes were changed

结论

这里省略一份“改进后的目录结构”，因为每个阶段或项目的结果无法预测。初始设置只应记录会实质影响决策、验证与后续工作的上下文。随着你对流程越来越熟悉，可以创建运行时间更长的任务，让它们受益于之前的开发周期，并在批准的边界内产出更一致、更可靠的结果。