This document aims to collect those best practices, which are surfacing in articles and blogpost related to harness engineering, extended with my own observations.
Developer Experience
Full Traversability
Humans and agents often solve problems through various levels of interaction. Because a fully autonomous approach is not always feasible, humans often have to step in and steer coding agents with fine-grained instructions. (See conductor vs. orchestrator in Google's paper on different interaction modes with agents.)
If the configurations for these interaction modes are not synchronized, the resulting complexity and confusion prevent efficient troubleshooting and harness configuration. A common foundation can be established through the use of ACP - Agent Client Protocol, agent plugins, and various skill dependency management tools from the harness landscape. This allows teams to use the same coding assistant with the same built-in system prompt, MCP configuration, skills, hooks, and LSP servers, improving the predictability of each run.
One of the most confusing aspects is how many defaults a coding agent contains: system prompts, tools with signatures and descriptions, internal TODO management, and many other predefined elements. There can be so many of these predefined mechanisms that they can differentiate coding agents even when they use the same model. For that reason, it is sensible to standardize on a single coding agent per team and use the same coding agent throughout CI/CD via ACP. If you are interested in how your coding agent works, I encourage you to explore ccunpacked.dev, enable detailed tracing, or attach a debugger to your coding agent to reveal all the prompts added to the context.
For a further reference, see how Stripe exposed tracing information for its minions. In addition, explore observability practices for implementation details.
Agile Amplification
Because LLMs generate output significantly faster than humans and coding agents are heavily optimized for writing code, they usually place immediate pressure on all subsequent steps.
The most obvious issue is code review: Teams often abandon the review phase in deference to the new technology, which creates accumulating cognitive debt and several serious problems.
One effective strategy is to look at the SDLC as a whole and start with the identified bottleneck. For example, starting with a code-review agent may put you in a better position later.
This observation has been discussed several times by practitioners, including ThoughtWorks and Google. Another example appears in Gregor Hohpe's book Platform Strategy, which includes a new section about AI platforms.
Cognitive Debt
One common pitfall practitioners discuss when using LLMs is the "slot machine effect": Each generated output can feel exciting while remaining overwhelmingly difficult to understand. It provides a brief dopamine rush and a false sense of productivity, making it difficult to resist "spinning the wheel again" and initiating another session with the LLM. In the long term, this can lead to burnout, depression, anxiety, and a loss of critical and analytical thinking.
Proactive practitioners deliberately avoid moving every piece of work into a chat window. They reserve part of each day for dedicated knowledge work, during which they analyze results and make decisions.
One commonly used behavioral framework is the 3R principle. The key is to remain actively engaged by taking technical responsibility for AI-generated content and, in the worst case, reviewing every word.
Extending this practice to reviews of agentic runs, loops, sessions, skill usage, and tool calls leads to a comprehensive understanding of how coding agents work and creates opportunities to improve the harness gradually.
Two potential obstacles to this practice are bloated pull requests and overly verbose documentation. These problems must be strategically eliminated, and practitioners should resist accepting them. Small, incremental code changes remain relevant, and semantic density in documentation remains necessary. Human review and accountability cannot be eliminated.
Developer Experience Surveys
An effective AI-enabled SDLC transformation requires both a sound high-level strategy and employee support. Many success stories identify developer-experience surveys as central to gauging engagement, with organizations hesitating to proceed when scores fall below a defined threshold.
Technology Building Blocks
Files as Agentic Memory
Why not use agentic memory layers such as cognee or agentmemory? Here are several reasons to avoid overcomplicating this simple concept:
- File-based storage scales alongside your code and requires no additional infrastructure.
- Version control provides versioning for these data entities alongside the code.
- Each unit of work is reviewable by examining the code changes and Markdown files together.
- Changes to agentic memory are traceable alongside code changes through version control.
In contrast to troubleshooting through MCP interfaces and binary files stored remotely in cloud infrastructure, simple Markdown files offer an efficient and transparent way to provide coding agents with long-term memory.
Besides considering the rules stored in Markdown files, you should account for your coding agent's existing training data. Duplicating training data by placing it in the agent's long-term memory as Markdown is not only counterintuitive, expensive, and slow but also increases cognitive debt. If in doubt, I encourage you to check the following resources on AI-generated AGENTS.md files and their efficiency.
There are three categories of agentic memory:
- Episodic memory (conversation history).
- Semantic memory (mostly
AGENTS.md). - Procedural memory (agent skills inside
SKILL.md).
Although these categories may seem vague, practitioners should remember the principle of progressive disclosure: coding agents may load AGENTS.md initially, but nothing prevents you from directing them to project documentation for further details. See the technology landscape's "Knowledge Base" section for scalable solutions.
Although documentation is stored in files for transparency, a search index can be layered over those files and exposed to coding agents through MCP. This reduces tool-calling errors and speeds up the retrieval of relevant sections of technical documentation. Tools such as QMD use a small model to build a lightweight semantic index over a documentation folder, similarly to a RAG system. As an intermediate option, ripgrep can provide faster conventional text search than the standard grep available in some coding assistants.
Further Reading: Anthropic, Google
Top comments (0)