김경종
84 lines
2.7 KiB
Markdown
84 lines
2.7 KiB
Markdown
# Codex Migration Guide
|
|
|
|
## Purpose
|
|
|
|
This repository was converted from a Claude-oriented Harness template into a Codex-oriented template.
|
|
|
|
## Mapping
|
|
|
|
| Claude surface | Codex surface | Repository path |
|
|
|---|---|---|
|
|
| `CLAUDE.md` | persistent repo instructions | `AGENTS.md` |
|
|
| `.claude/commands/*.md` | repo skills | `.agents/skills/*/SKILL.md` |
|
|
| Claude sub-agents | project-scoped custom agents | `.codex/agents/*.toml` |
|
|
| `.claude/settings.json` hooks | Codex hooks | `.codex/hooks.json` |
|
|
| `claude -p` automation | `codex exec` automation | `scripts/execute.py` |
|
|
| ad hoc slash commands | optional plugin command layer | `plugins/harness-engineering/commands/` |
|
|
|
|
## Repository surfaces
|
|
|
|
### `AGENTS.md`
|
|
|
|
Codex loads `AGENTS.md` as the persistent instruction file for the repository.
|
|
|
|
Use it for:
|
|
|
|
- project-level rules
|
|
- architecture constraints
|
|
- workflow expectations
|
|
- validation commands
|
|
|
|
### `.agents/skills/`
|
|
|
|
Repo skills are the primary reusable workflow layer.
|
|
|
|
- `harness-workflow`: plan phases and generate `phases/` files
|
|
- `harness-review`: review changes against Harness docs and rules
|
|
|
|
These are automatically discoverable by Codex in this repository.
|
|
|
|
### `.codex/agents/`
|
|
|
|
Custom agents are defined as standalone TOML files.
|
|
|
|
- `phase_planner`: read-heavy planner for decomposing work into steps
|
|
- `harness_reviewer`: read-only reviewer for architecture and test compliance
|
|
|
|
Use these only when the user explicitly asks Codex to fan out work across subagents.
|
|
|
|
### `.codex/hooks.json`
|
|
|
|
As of 2026-04-15, Codex documents hooks as experimental and disabled on native Windows.
|
|
|
|
This repo still ships hook definitions because they work on macOS, Linux, and WSL once `codex_hooks` is enabled. On native Windows, use `python scripts/validate_workspace.py` manually or through `scripts/execute.py`.
|
|
|
|
### `plugins/harness-engineering/`
|
|
|
|
This is an optional repo-local plugin that exposes Harness slash-command prompts through the local marketplace.
|
|
|
|
Install path:
|
|
|
|
1. Restart Codex.
|
|
2. Open `/plugins`.
|
|
3. Choose the local marketplace `Local Harness Engineering`.
|
|
4. Install `harness-engineering`.
|
|
|
|
## Automation
|
|
|
|
`scripts/execute.py` now calls `codex exec` instead of `claude -p`.
|
|
|
|
Execution model:
|
|
|
|
- inject `AGENTS.md` and `docs/*.md` into each step prompt
|
|
- run steps in order
|
|
- retry failed steps up to 3 times with prior error feedback
|
|
- persist step outputs under `phases/{phase}/stepN-output.json`
|
|
- create code and metadata commits after successful steps
|
|
|
|
## Validation
|
|
|
|
`python scripts/validate_workspace.py` is the repo-level fallback validator.
|
|
|
|
- If `package.json` exists, it auto-runs available `npm run lint`, `npm run build`, and `npm run test`.
|
|
- If the project needs another validation chain, set `HARNESS_VALIDATION_COMMANDS` to newline-separated commands.
|