loading
loading
How to Codify Nuance in Agentic Engineering An agent can produce a change that passes its tests and still violates a commitment the system needs to keep. The missing context might be a supported client in another repository, the reason an earlier review rejected the same change, or a policy that determines when a dependency can be retired. Human judgment draws on knowledge about systems, people, and the conditions around a decision. Making some of that knowledge available to agents is an engineering problem we can start to solve. That thought stayed with me after a conversation on The Agentic Review with Zichuan Xiong, Global Head of AIOps at Thoughtworks, and Itamar Friedman, Qodo’s CEO and co-founder. Zichuan’s technical answers kept reaching into process, psychology, organizational relationships, and mental models. There are levels and layers we’re translating here. I think nuance is a useful way to describe the distinctions that change what a good engineering decision looks like. So how do we codify it? A starting point is to represent those distinctions with evidence, retrieve them for the right task, and verify whether they change the agent’s decisions appropriately. What nuance looks like in an engineering change Consider an illustrative task: remove a deprecated API response field called legacy_status. The agent updates the server and its tests. Everything passes. But a supported mobile client, maintained in another repository, still reads that field. An earlier review explains why the API team retained it. A support policy determines which client versions remain supported. Removal requires evidence that those clients have migrated or reached the end of support. Each condition changes the decision. An experienced engineer may know where to investigate because they remember that review, understand the mobile release cycle, or recognize that “deprecated” doesn’t mean every consumer has stopped depending on something. That knowledge spans code, organizational commitments, procedures, and human understanding. In this illustrative API change, dependencies, support commitments, retirement checks, and reviewer knowledge shape whether legacy_status can be removed. Make the relevant relationships inspectable Codebase intelligence helps reconstruct relationships an experienced maintainer would investigate: consumers, contracts, architectural boundaries, and the history behind a constraint. In this example, the investigation connects the API field to client code, then retrieves the review that explains its retention. Each finding should point back to inspectable evidence: a repository, file, revision, or review discussion. Qodo’s Codebase Wisdom skill brings code, pull-request history, and cross-repository relationships into a coding agent’s investigation. Its guidance also distinguishes remote evidence from the exact local worktree: local tools establish the branch, uncommitted changes, and tests relevant to the change being made. What matters is the reasoning those connections support: this field participates in a compatibility commitment that the server’s tests don’t cover. There are limits. A missing relationship in an index doesn’t establish that no dependency exists. Historical rationale needs checking against current code and policy. A client reference at a particular revision doesn’t, by itself, establish which versions are deployed or supported. The agent should expose what it searched, what it found, and what remains unknown. Preserve the reason and its conditions Agent memory preserves knowledge across tasks. For this example, it could retain the reason a previous removal was rejected, along with the conditions under which that reason remains relevant. A useful record needs more than “keep this field.” The following is an illustrative record, not a Qodo memory schema: scope: public-api/account-response knowledge: supported mobile clients read legacy_status reason: server tests omit those client contracts evidence: - "<consumer code and revision>" - "<review explaining compatibility>" - "<current support policy>" applies_when: dependent clients remain supported retire_when: migration or end of support is verified status: candidate_for_validation Qodo describes its memory system as carrying knowledge from review outcomes forward. The broader design question is how to validate, scope, refresh, and retire that knowledge. An accepted fix is a learning signal. It doesn’t prove the underlying reasoning is correct, or that it applies indefinitely. If the mobile clients migrate, the old conclusion needs to change. Preserving the reason and its conditions gives a future reviewer something to reassess. Bring standards and skills into the task These mechanisms serve different purposes. Codebase intelligence supplies relationships and evidence. Memory preserves learned reasoning. Standards describe expectations; skills provide procedures for applying them. Here, a standard might require compatibility evidence before removing a public response field. A skill could guide the agent through the investigation: - Find consumers and record the repositories and revisions inspected. - Check which dependent client versions are still supported. - Retrieve the rationale behind the existing constraint. - Select contract tests that exercise the affected behavior. - Explain whether the evidence supports removal, continued compatibility, or further investigation. Qodo’s Get Rules skill retrieves applicable coding standards for a concrete task. Its Rule Miner extracts standards from actionable review feedback that led to fixes. Turning experience into policy still requires checking scope and exceptions. Retrieving guidance is one step in that workflow. The team still needs to decide which tests, reviews, and repository controls determine whether a change can merge. The harness, the software organizing an agent’s tools and execution, brings these inputs into the task. Review outcomes can then inform the outer learning loop: revising future context, guidance, and checks. The UX matters too. People need to see the evidence, applicability, and uncertainty behind a recommendation so they can challenge it. A proposed workflow for bringing context into agent tasks and learning from review outcomes. Historical knowledge needs validation against current code and policy. Test whether the knowledge changes the decision I’d evaluate this design with cases where the appropriate decision changes: - A supported client still depends on the field. The agent should preserve compatibility and identify the dependency. - Migration or end of support is verified. The agent should recognize that the earlier restriction can be retired, subject to the remaining checks. - An unrelated change touches the same API. The agent should avoid imposing an irrelevant restriction. - Support status is unknown. The agent should identify the missing evidence rather than confidently approve removal. Compare the same cases with and without the relevant knowledge. Check the decisions and explanations against expectations established independently of the agent being evaluated. Look at whether it cites the right evidence, applies the constraint only where it belongs, and changes its recommendation when the facts change. A system that always says “keep the field” hasn’t learned the distinction. We’d need that evidence before claiming we’ve closed the junior–senior knowledge gap. Making experienced reasoning inspectable gives us something concrete to test. Start with one decision your team keeps revisiting Choose a recurring review question. Capture the reason behind the answer, the evidence supporting it, and the conditions that would change it. Then test whether an agent uses that knowledge appropriately in a new task. This conversation left me thinking about how much engineering knowledge lives in the reasons behind a decision. Codifying nuance starts with making those reasons available for inspection, challenge, and revision. Listen to the full conversation with Zichuan Xiong on The Agentic Review. To explore context-aware code review in your own workflow, start a free Qodo trial.
document fetched 2026-10-24 11:26 · canonical https://qodo.ai/blog/how-to-codify-nuance-in-agentic-engineering