Agent Harness Instructions

Efficiency

Optimize for best result per token, not lowest token use.

For small, obvious tasks, act directly. Before broad work, cheaply scope first: count relevant files/items/search hits, batch inspection, use tools like rg, find, jq, scripts, or structured parsers, and summarize large outputs unless I ask for full text.

Pause and offer 2-3 options before proceeding if the task may exceed ~30k tokens, touches ~20+ files/items/API calls, has ambiguous scope like "all/everything," or has a real quality/cost tradeoff. For each option, state scope, rough cost/time, completeness, and your recommendation.

Do not reduce quality just to save tokens. If broad context is genuinely needed, say so and ask. Only mention token savings when they are substantial.

Project Memory

Use generic cross-agent project files.

Prefer AGENTS.md for agent-facing instructions over harness-specific files like CLAUDE.md, unless the harness requires its own file. Keep it portable across Codex, Claude, Co-work, Anti-Gravity, and other agent tools. Include setup commands, conventions, workflow notes, and pitfalls. If harness-specific files exist, reference AGENTS.md instead of duplicating content.

Create or update HUMANS.md for human-facing orientation when meaningful project work happens. Keep it brief and include:

• Last worked date
• Agent harness used
• Harness project/session name, if known
• Local path
• Parent project/sub-project relationship
• Return notes, such as where the main work happened or how to resume

Suggested format:

# Human Notes

## Last Accessed
- Date:
- Agent harness:
- Harness project/session name:
- Local path:

## Project Context
- Parent project:
- Sub-project:
- Related folders:

## Return Notes
-

Project Organization

Use this mental model:

Harness project = long-lived context domain
Thread = one focused workstream
Folder = source of truth

For broad work domains, use one harness-level project rooted at the main folder, then use focused threads for sub-projects or workstreams. Prefer separate harness projects only when the work has a different context domain, would pollute shared memory, is confidential, or is large enough to need its own durable knowledge base.

When working locally, start from the sub-project folder when the task is mostly about that sub-project. Start from the root folder when the task needs shared context across the broader project.