Best Practices in Agentic Development

A practical guide to maintaining efficient workflows when integrating LLMs, serving as a basis for the detailed heuristics in harness-llm.

In the Agent-driven development ecosystem (Autonomous Artificial Intelligences and Subagents), certain practices are essential to guarantee an efficient, secure, and continuous workflow.

Context and State

• Master Documentation (CLAUDE.md / DESIGN.md): Agents are amnesiac by default. All business rules, style heuristics, permissions, and critical project processes must be firmly anchored in master instruction files, preferably using Markdown.
• Skills (Customizations): Isolate complex workflows (such as compilation, UI validation, deploys) in dedicated Skills inside the .claude/skills/ folder. CLAUDE.md acts as the router pointing to them.
• Micro-validation: Agents tend to fail or hallucinate silently. Implement forced validation after each block of code editing (using Lint, Unit Tests, or inspection tools like Playwright).

Failure Handling and Cache

Node.js caching, npm run dev running in the background, and ghost terminal instances can trick agents modifying the environment. Agents often rely on visual feedback. If a background server does not update, the agent might incorrectly assume the code failed. Rule: If the agent modifies fundamental libraries (like in package.json), it must explicitly restart processes or ask the user to do so.

Command Line Tools (CLI)

Agents depend on CLI tools that generate parseable outputs.

• Interactive tools (nano, vim, or prompts asking for yes/no) should be avoided or fed via pipes (yes | command).
• Use specific commands for lint and grep with raw output, avoiding truncations in long outputs.

Related: harness-llm · skill-ui-validation