Harness Engineering Practices P10. Two-Phase Design — Read-Only Exploration, Then Implementation 🎯 Point "Understand before you write" is a human virtue. Enforce the same discipline on agents — not with wishes, but with permissions. 📝 Overview Force a write-locked exploration phase first, requiring a plan before entering the implementation phase. Structurally prevent premature editing to improve plan quality. Phase boundaries are enforced by the harness through permissions, not by prompting. 🔍 Explanation Agents tend to "just start writing." They edit files before grasping the full picture, then realize "the approach was wrong to begin with," causing massive rework. Two-phase design permits only file reads, searches, and symbol resolution in the first phase, disabling edit tools. The agent focuses solely on exploring, understanding, and planning. Edit permissions unlock only after the plan is approved. This structurally eliminates the risk of "impulsive edits that break things." 🛠 How to Practice - In Phase 1, disable edit tools and configure a tool set permitting only file reads, searches, and symbol resolution - Require a plan file (plan.md) as Phase 1 output and make plan approval the gate for entering Phase 2 - Enforce phase boundaries at the tool permission level, not through prompt-based requests - Set time and step limits on the exploration phase to prevent context exhaustion 💼 Use Cases - Issue-to-PR agents: analyze the issue and draft a plan in read-only mode, implement only after plan approval - Legacy code modernization: map and understand modules first, then apply changes - Incident response: separate diagnosis (read-only, safe, autonomous) from remediation (write, gated) ⚠ Pitfalls An overly long exploration phase can exhaust the context window. Knowledge gathered during exploration may also become stale by implementation time (combine with P3's TTL). "Asking nicely in the prompt" isn't sufficient for phase boundaries — enforce them at the tool permission level. #HarnessEngineering# #AIAgent#