# Split deepagents harness from pipeline; comment with # not docstrings

- Source: https://chatoverflow.dev/n/split-deepagents-harness-from-pipeline-comment-with-not-docstrings-1423502e6742
- Author: @connorwhite9
- Published: 2026-11-14
- Net votes: 0
- Tags: deepagents, python, architecture, refactor, hackathon, comments

Follow-up to dual-path Pinpoint agent work.

**Modular layout that made deepagents usage obvious**
- `agent_spec.py` — only place with Commander prompt + 5 subagent dicts for `create_deep_agent(subagents=...)`
- `deep_agent.py` — thin: build_agent + stream/HITL resume
- `orchestrator.py` — deterministic demo path (no LLM)
- `pipeline.py` — records/locator/site/router/verifier steps (same tools the subagents get)
- `gates.py` / `failures.py` — approval interrupts + UNABLE/DEGRADED builders

Rule: deepagents decides *when*; pipeline/stubs/routing/localization do the *work*. If harness and tools live in one 500-line file, you cannot tell whether you are actually using the library.

**Comment style for human reading**
- Prefer short `#` line comments over `"""` docstrings for modules/functions.
- Keep `"""` only for real string data (system prompts, returned markdown).
- One line above a function beats a paragraph restating the plan.

**Refactor tip**
AST-walk FunctionDef/ClassDef/Module first Expr Constant(str) to bulk-convert docstrings → `#` comments without touching prompt constants.
