<?xml version="1.0" encoding="UTF-8"?><rss xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:atom="http://www.w3.org/2005/Atom" version="2.0" xmlns:cc="http://cyber.law.harvard.edu/rss/creativeCommonsRssModule.html">
    <channel>
        <title><![CDATA[Stories by Weidian Huang on Medium]]></title>
        <description><![CDATA[Stories by Weidian Huang on Medium]]></description>
        <link>https://medium.com/@weidianhuang?source=rss-865711e189d8------2</link>
        <image>
            <url>https://cdn-images-1.medium.com/fit/c/150/150/0*3PbUJnShmczXmIRF</url>
            <title>Stories by Weidian Huang on Medium</title>
            <link>https://medium.com/@weidianhuang?source=rss-865711e189d8------2</link>
        </image>
        <generator>Medium</generator>
        <lastBuildDate>Fri, 20 Nov 2026 05:04:59 GMT</lastBuildDate>
        <atom:link href="https://medium.com/@weidianhuang/feed" rel="self" type="application/rss+xml"/>
        <webMaster><![CDATA[yourfriends@medium.com]]></webMaster>
        <atom:link href="http://medium.superfeedr.com/" rel="hub"/>
        <item>
            <title><![CDATA[The Evolution of AI Harness Engineering: From Defining How to Defining What Good Means]]></title>
            <link>https://weidianhuang.medium.com/the-evolution-of-ai-harness-engineering-from-defining-how-to-defining-what-good-means-4579ce5baeeb?source=rss-865711e189d8------2</link>
            <guid isPermaLink="false">https://medium.com/p/4579ce5baeeb</guid>
            <category><![CDATA[ai]]></category>
            <category><![CDATA[ai-agent]]></category>
            <category><![CDATA[harness-engineering]]></category>
            <category><![CDATA[ai-coding]]></category>
            <dc:creator><![CDATA[Weidian Huang]]></dc:creator>
            <pubDate>Sun, 20 Sep 2026 00:45:00 GMT</pubDate>
            <atom:updated>2026-09-20T00:45:00.843Z</atom:updated>
            <content:encoded><![CDATA[<p>I think we are entering an interesting transition in <strong>AI harness engineering</strong>.</p><p>A useful mental model is:</p><blockquote>Agent = Model + Harness</blockquote><p>But the harness itself can be split into two layers:</p><h3>1. Platform harness</h3><p>Provided by tools such as Codex, GitHub Copilot, Claude Code, etc.</p><p>It increasingly handles generic agent capabilities such as:</p><p>→ context management<br>→ tool execution<br>→ sandbox/environment<br>→ planning and reasoning loops<br>→ state and long-running tasks<br>→ subagents / parallel execution<br>→ retries and recovery</p><p>For example, the Codex harness already manages much of the interaction between the model, tools, execution environment, context and agent lifecycle.</p><h3>2. Your project harness</h3><p>This is the layer your own engineering team builds around the agent.</p><p>It contains things the platform cannot know by itself:</p><p>→ architecture constraints<br>→ repository knowledge<br>→ company-specific coding rules<br>→ security policies<br>→ domain knowledge<br>→ custom tools<br>→ build/test commands<br>→ emulator or simulator control<br>→ UI/screenshot verification<br>→ architecture checks<br>→ regression tests<br>→ evaluators<br>→ success criteria</p><p>The distinction I find increasingly useful is:</p><pre>Platform harness<br>↓<br>figures out HOW<br><br>Your project harness<br>↓<br>defines WHAT GOOD MEANS</pre><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*GEd1W7Wsk-pMurD3gL0r9g.png" /></figure><p>As models become stronger, and platform harnesses become more capable, I expect our own project harnesses to become smaller and more declarative.</p><p>Instead of telling the agent:</p><p>1. Read these files<br>2. Find the affected module<br>3. Create a plan<br>4. Implement<br>5. Compile<br>6. Fix errors<br>7. Run tests<br>8. Launch emulator<br>9. Capture screenshot<br>10. Compare UI<br>11. Retry...</p><p>We may increasingly just provide:</p><pre>Goal:<br>Implement feature X.<br><br>Constraints:<br>Follow our architecture.<br>Don&#39;t change the API contract.<br>Use our design system.<br><br>Success criteria:<br>✓ Build passes<br>✓ Tests pass<br>✓ Architecture check passes<br>✓ Security checks pass<br>✓ UI verification passes</pre><p>Then let the agent decide the execution path.</p><p>A very interesting example of this transition is GitHub Actions.</p><p>Traditional GitHub Actions are highly explicit:</p><p>&quot;YAML → job → step → script → result&quot;</p><p>You describe a large part of HOW the automation should execute.</p><p>GitHub&#39;s newer Agentic Workflows introduce a different abstraction.</p><p>You can describe an automation using Markdown and natural-language instructions, while YAML frontmatter specifies things such as triggers and permissions.</p><p>GitHub then compiles that agentic workflow back into a standard Actions workflow for controlled execution.</p><p>So conceptually we are moving from:</p><p>Traditional automation</p><p>&quot;Human → explicit YAML workflow → scripts&quot;</p><p>toward:</p><p>Agentic automation</p><p>&quot;Human → intent + constraints → agent → tools → verification&quot;</p><p>YAML isn&#39;t necessarily disappearing.</p><p>Scripts aren&#39;t disappearing either.</p><p>In fact, deterministic tools may become even more important.</p><p>I still want:</p><p>&quot;./gradlew test&quot;</p><p>to behave deterministically.</p><p>I still want:</p><p>&quot;architecture-check&quot;</p><p>to return PASS or FAIL.</p><p>I still want security policies to be enforceable rather than something the model merely &quot;remembers.&quot;</p><p>What changes is the layer above them.</p><p>Instead of humans specifying every execution step, the agent increasingly decides how to combine those deterministic capabilities to achieve the goal.</p><p>That makes me think the long-term project harness will focus less on controlling agent reasoning and more on providing:</p><blockquote><strong>Environment + Context + Constraints + Tools + Verification</strong></blockquote><p>As the model gets smarter:</p><p>Skills may become thinner.<br>Workflows may become thinner.<br>Agent planning becomes stronger.<br>Platform harnesses absorb more generic orchestration.</p><p>But the project harness remains important because somebody still needs to define:</p><p><strong>What does &quot;correct&quot; mean for OUR system?</strong></p><p>That may ultimately be the most durable part of harness engineering.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=4579ce5baeeb" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Harness Engineering: Building Coding Rules Into an AI Harness]]></title>
            <link>https://weidianhuang.medium.com/harness-engineering-building-coding-rules-into-an-ai-harness-1b259f69317a?source=rss-865711e189d8------2</link>
            <guid isPermaLink="false">https://medium.com/p/1b259f69317a</guid>
            <category><![CDATA[vibe-coding]]></category>
            <category><![CDATA[ai-agent]]></category>
            <category><![CDATA[harness-engineering]]></category>
            <category><![CDATA[ai]]></category>
            <category><![CDATA[android]]></category>
            <dc:creator><![CDATA[Weidian Huang]]></dc:creator>
            <pubDate>Mon, 31 Aug 2026 13:00:16 GMT</pubDate>
            <atom:updated>2026-08-31T13:01:45.041Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*kVWWhN2ZvkGa58vA1vl5mA.png" /></figure><p>This article is part of my <strong>AI Coding Harness Engineering</strong> series, where I explore how to make AI coding agents more reliable for real software engineering work.</p><p>Rather than focusing only on model capability or prompt engineering, this series looks at the agentic system around the model: specifications, task decomposition, persistent context, verification gates, UI feedback, evaluator loops, and long-running workflows.</p><p><strong>Part 1 — </strong><a href="https://medium.com/@weidianhuang/harness-engineering-how-to-turn-ai-coding-agents-into-a-reliable-engineering-team-16af4f27775c"><strong>Why AI Coding Agents Need a Harness</strong></a><br>Why coding agents need an engineering harness around them, and the core failure modes the harness is designed to control.</p><p><strong>Part 2 — </strong><a href="https://medium.com/@weidianhuang/harness-engineering-how-to-set-up-an-android-agent-harness-b7154d9e3471"><strong>How to Set Up an Android Agent Harness</strong></a><br>A practical guide on using the Android agent harness in your project.</p><p><strong>Part 3 — </strong><a href="https://medium.com/@weidianhuang/harness-engineering-building-a-test-harness-that-can-prove-software-works-9c15ca65e8e5"><strong>Building a Test Harness That Can Prove Software Works</strong></a><strong><br></strong>A practical guide to tracing software requirements through tests, evidence, and review using an Android harness.</p><p><strong>Part 4 — </strong><a href="https://medium.com/@weidianhuang/harness-engineering-why-ui-design-should-start-inside-harness-planning-ffe27b89412b"><strong>Why UI Design Should Start Inside Harness Planning</strong></a><br>UX improves when design generation, harness planning, and runtime verification work together in one continuous loop.</p><p><strong>Part 5 — </strong><a href="https://medium.com/@weidianhuang/harness-engineering-building-coding-rules-into-an-ai-harness-1b259f69317a"><strong>Building Coding Rules Into an AI Harness</strong></a><strong><br></strong>Discover how an AI coding harness turns fragile rule-following into reliable quality by combining context-aware requirements, deterministic scripts, and independent evaluation.</p><p><strong>Part 6 — </strong><a href="https://medium.com/@weidianhuang/the-harness-matters-more-than-the-model-you-pick-ba5f8d66c238"><strong>Harnesses Raise the Floor and Lower the Blast Radius</strong></a><br>How engineering constraints affect smaller and larger models differently, and why stronger models still benefit from a well-designed harness.</p><p><strong>Part 7 — </strong><a href="https://medium.com/@weidianhuang/harness-engineering-building-a-retrospective-feedback-loop-b535915d0200"><strong>Building a Retrospective Feedback Loop</strong></a><strong><br></strong>How to build a continuous-improvement harness system around your project.</p><p>Source repositories:</p><ul><li><a href="https://github.com/hwdavr/NotesTakingApp/tree/master">NotesTakingApp</a></li><li><a href="https://github.com/hwdavr/android-agent-harness">android-agent-harness</a></li></ul><p>AI can generate code quickly. The harder problem is making that code consistently follow the standards of a real production codebase.</p><p>A common first attempt is simple: put coding rules in a prompt, skill, or workflow. Tell the model not to put business logic in Composables, not to hardcode strings, to keep DTOs in the data layer, and to write tests.</p><p>That helps — but it is not enforcement.</p><p>A workflow can tell a model which stage comes next. A skill can load the relevant coding rules and explain how to apply them. Neither guarantees that the generated code follows every rule exactly. Models can miss a rule, interpret it too broadly, or produce code that looks correct while violating the intended architecture.</p><p>The harness in this repository treats coding rules as a layered quality system instead of a single prompt instruction.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*X0GMtbCic63ntmfyLrEUkg.png" /></figure><h3>Make rule applicability explicit during requirements</h3><p>Not every coding rule applies to every feature.</p><p>A UI change may need Compose, localization, and accessibility rules. An API change needs DTO, OpenAPI, mapper, and integration-test rules. A feature without navigation changes should not invent navigation work merely to satisfy a checklist.</p><p>That is why the harness includes a Rule Applicability matrix in the requirement artifact. Every feature must explicitly decide whether each rule family is:</p><ul><li>Required</li><li>Not applicable — &lt;feature-specific reason&gt;</li><li>Exception — approved by &lt;user/date&gt;</li></ul><p>The matrix covers:</p><ul><li>Architecture</li><li>Real implementation / no dummy code</li><li>Testing</li><li>Compose UI</li><li>Localization</li><li>Navigation</li><li>API contracts</li><li>Observability</li><li>Analytics</li></ul><p>For every required rule, the requirement records both the trigger and the planned evidence. This matters because the model now knows not only <em>what</em> rules exist, but <em>when and where</em> they apply to the current feature.</p><p>For example, “all interactive elements need a stable testTag” becomes much more actionable when the requirement identifies the screen, its key actions, and the UI-test evidence expected later.</p><h3>Turn detectable rules into deterministic gates</h3><p>Some rules are mechanical. A script can detect them more reliably than a model reviewing its own output.</p><p>Examples include:</p><ul><li>A UI file importing a data-layer DTO</li><li>A ViewModel importing Retrofit or Room</li><li>A domain class importing Android framework types</li><li>Hardcoded text or colors in Compose</li><li>Missing testTags on interactive UI</li><li>A repository implementation missing @Singleton</li><li>A ViewModel without a matching test</li><li>A misplaced ViewModel, UseCase, repository, or mapper</li></ul><p>The harness runs these checks as code-quality gates:</p><pre>./gradlew assembleDebug<br>./gradlew ktlintCheck<br>./gradlew detekt<br>./gradlew lintDebug<br>bash harness/scripts/check-compose-rules.sh<br>bash harness/scripts/check-localization-rules.sh<br>bash harness/scripts/check-architecture-rules.sh<br>bash harness/scripts/check-navigation-rules.sh<br>bash harness/scripts/check-coverage.sh app/build/reports/kover/reportDebug.xml</pre><p>A non-zero exit code means the stage cannot pass. This is the important shift: the model is not asked to <em>claim</em> that it followed the rules. It must produce code that passes an objective check.</p><p>Scripts are deterministic, but they are not magic. They only prove the conditions they actually check.</p><h3>Use evaluators for semantic rules</h3><p>Many of the most valuable rules cannot be reduced safely to a regex.</p><p>A script cannot reliably determine whether:</p><ul><li>A Composable contains business logic</li><li>A ViewModel has too much domain decision-making</li><li>Loading, success, and error states are complete</li><li>A callback has a reachable production path</li><li>A branch compiles but never implements the required behaviour</li><li>A sealed class is justified instead of a simpler UiState</li><li>A feature genuinely meets its acceptance criteria</li></ul><p>These need semantic review.</p><p>In the evaluation stage, an independent evaluator reads the approved requirements, reconciles every rule-applicability decision against the diff, reruns the quality gates, and reviews the code and tests adversarially.</p><p>The evaluator does not simply ask, “Does this code look reasonable?” It traces requirements to production entry points, state transitions, callbacks, cleanup paths, tests, and observable outcomes.</p><p>This is particularly important for the “no dummy code” rule. A function returning emptyList(), a no-op click handler, or a placeholder branch can compile and pass formatting checks. It is still a failed implementation if the requirement says that path must search, persist, navigate, or display an error state.</p><h3>Treat scripts and evaluators as complementary</h3><p>The architecture enforcement matrix makes the split explicit:</p><ul><li>Scripted rules are fast, repeatable, and deterministic.</li><li>Evaluator rules cover intent, architecture, completeness, and semantics.</li><li>Some rules need both.</li><li>A small number remain human decisions, such as approving an explicit exception or confirming AI-generated code has received appropriate review.</li></ul><p>This is stronger than relying on either scripts or an evaluator alone. Scripts catch repeatable patterns every time; an evaluator catches the ways a model can satisfy syntax while missing the product requirement.</p><h3>The quality ceiling is in the rule detail</h3><p>An AI harness cannot make a weak model perfect. But once the model is capable of following instructions and responding to feedback, code quality depends heavily on the quality of the rules.</p><p>Vague rule:</p><blockquote><em>Keep the UI clean.</em></blockquote><p>Useful rule:</p><blockquote><em>Composables render </em><em>UiState and invoke callbacks only; business rules, repository calls, DTO mapping, and data transformations belong outside the UI layer. Key interactive elements must have stable descriptive </em><em>testTags. The code-quality gate must pass and the evaluator must review semantic compliance.</em></blockquote><p>The second rule defines ownership, boundaries, exceptions, and evidence. It gives the model less room to guess — and gives the harness a concrete way to reject bad output.</p><p>The goal is not to trust the model more. It is to build a process where good code is easier to produce, bad code is easier to detect, and no stage can pass without evidence.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=1b259f69317a" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Harness Engineering: Building a Retrospective Feedback Loop]]></title>
            <link>https://weidianhuang.medium.com/harness-engineering-building-a-retrospective-feedback-loop-b535915d0200?source=rss-865711e189d8------2</link>
            <guid isPermaLink="false">https://medium.com/p/b535915d0200</guid>
            <category><![CDATA[harness-engineering]]></category>
            <category><![CDATA[ai-agent]]></category>
            <category><![CDATA[agentic-ai]]></category>
            <category><![CDATA[android]]></category>
            <category><![CDATA[ai]]></category>
            <dc:creator><![CDATA[Weidian Huang]]></dc:creator>
            <pubDate>Fri, 28 Aug 2026 10:54:06 GMT</pubDate>
            <atom:updated>2026-08-31T13:23:00.236Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*f4LRW_GO9cV_wFyhgu1aTA.png" /></figure><p>This article is part of my <strong>AI Coding Harness Engineering</strong> series, where I explore how to make AI coding agents more reliable for real software engineering work.</p><p>Rather than focusing only on model capability or prompt engineering, this series looks at the agentic system around the model: specifications, task decomposition, persistent context, verification gates, UI feedback, evaluator loops, and long-running workflows.</p><p><strong>Part 1 — </strong><a href="https://medium.com/@weidianhuang/harness-engineering-how-to-turn-ai-coding-agents-into-a-reliable-engineering-team-16af4f27775c"><strong>Why AI Coding Agents Need a Harness</strong></a><br>Why coding agents need an engineering harness around them, and the core failure modes the harness is designed to control.</p><p><strong>Part 2 — </strong><a href="https://medium.com/@weidianhuang/harness-engineering-how-to-set-up-an-android-agent-harness-b7154d9e3471"><strong>How to Set Up an Android Agent Harness</strong></a><br>A practical guide on using the Android agent harness in your project.</p><p><strong>Part 3 — </strong><a href="https://medium.com/@weidianhuang/harness-engineering-building-a-test-harness-that-can-prove-software-works-9c15ca65e8e5"><strong>Building a Test Harness That Can Prove Software Works</strong></a><strong><br></strong>A practical guide to tracing software requirements through tests, evidence, and review using an Android harness.</p><p><strong>Part 4 — </strong><a href="https://medium.com/@weidianhuang/harness-engineering-why-ui-design-should-start-inside-harness-planning-ffe27b89412b"><strong>Why UI Design Should Start Inside Harness Planning</strong></a><br>UX improves when design generation, harness planning, and runtime verification work together in one continuous loop.</p><p><strong>Part 5 — </strong><a href="https://medium.com/@weidianhuang/harness-engineering-building-coding-rules-into-an-ai-harness-1b259f69317a"><strong>Building Coding Rules Into an AI Harness</strong></a><strong><br></strong>Discover how an AI coding harness turns fragile rule-following into reliable quality by combining context-aware requirements, deterministic scripts, and independent evaluation.</p><p><strong>Part 6 — </strong><a href="https://medium.com/@weidianhuang/the-harness-matters-more-than-the-model-you-pick-ba5f8d66c238"><strong>Harnesses Raise the Floor and Lower the Blast Radius</strong></a><br>How engineering constraints affect smaller and larger models differently, and why stronger models still benefit from a well-designed harness.</p><p><strong>Part 7 — </strong><a href="https://medium.com/@weidianhuang/harness-engineering-building-a-retrospective-feedback-loop-b535915d0200"><strong>Building a Retrospective Feedback Loop</strong></a><strong><br></strong>How to build a continuous-improvement harness system around your project.</p><p>Source repositories:</p><ul><li><a href="https://github.com/hwdavr/NotesTakingApp/tree/master">NotesTakingApp</a></li><li><a href="https://github.com/hwdavr/android-agent-harness">android-agent-harness</a></li></ul><p>A software harness is the delivery system around the code. It is not a static checklist that is written once and then forgotten. In this repository, the harness is a set of cooperating systems that guide an agent from requirements to implementation, verification, evaluation, and human review.</p><h3><strong>The Harness Systems in This Repository</strong></h3><p>In the previous articles (Part 3–5), we introduced three complementary harnesses in this system:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*bE463x3Et5HkPNUZgvGyFw.png" /></figure><p>A good software harness system can reduce most bugs during the generation stage. The bugs that remain are caused by missing or ambiguous requirements or by platform limitations. The harness can expose those gaps and make them explicit, but it cannot decide a requirement that was never written or create a capability the platform does not provide.</p><h3>What the harness-retrospective Skill Improves</h3><p>The retrospective skill is the feedback mechanism for all of these systems. When a bug, false pass, skipped check, misleading artifact, or review finding reaches a human, it asks which part of the delivery system should have caught it earlier or explained it more clearly. Later in this article, we’ll show how to use this skill to create a new harness that strengthens and extends the existing system.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*uavVNPRdCtR18j6ovZYl5A.png" /></figure><p>The skill does not turn every application failure into a harness change. Application defects stay in the bug-fixing workflow, unclear requirements return to planning, and platform limitations go to an architecture or product decision. The retrospective changes the harness only when the harness itself was missing, misleading, or too weak.</p><p>The central idea is simple:</p><blockquote>After a delivery loop reaches human review, and a bug is found and fixed, inspect the harness itself. Ask whether the workflow, skill, test plan, fixture, validator, or evidence gate should have prevented or exposed the bug earlier.</blockquote><p>The goal is not to blame the previous implementation. The goal is to make the next loop stronger, so the harness becomes more capable without becoming unstable or bureaucratic.</p><h3>The Two Loops</h3><p>A normal feature loop changes the application:</p><pre><br>Analyze -&gt; Clarify -&gt; Plan -&gt; Write tests -&gt; Implement -&gt; Verify -&gt; Human review</pre><p>The retrospective loop changes the delivery system:</p><pre>Bug found -&gt; Classify -&gt; Fix the product bug -&gt; Re-run verification<br>                               |<br>                     Inspect the harness<br>                               |<br>           Repair workflow, skill, test, fixture, or gate<br>                               |<br>              Add regression evidence -&gt; Human review</pre><p>These loops must remain separate. A product bug belongs in the product workflow. A harness gap belongs in the harness-retrospective workflow. Mixing them makes it easy to change the wrong thing or quietly weaken the acceptance criteria.</p><p>A useful rule is:</p><blockquote>First restore the application to the required behavior. Then ask why the harness did not catch the problem at the right stage.</blockquote><h3>What Counts as a Harness Problem?</h3><p>Not every failed test means the harness is broken. The retrospective skill uses explicit classifications to prevent overcorrecting:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*RNmg_KGWYlOJOZJr9oxu0w.png" /></figure><p>The most important discipline is not relabeling an application defect as a harness defect just because the application failed. A retrospective is warranted when the process should have caught the defect earlier, failed to test the relevant boundary, or reported misleading evidence.</p><h3>Retrospectives Belong at Human Review Boundaries</h3><p>A harness should evolve continuously across delivery loops, but an agent should not rewrite its own process in the middle of an active feature. Keeping each loop stable makes the change reviewable; applying the lesson at the boundary lets the next loop start with a stronger system.</p><p>A better rhythm is to complete one workflow loop, produce the required evidence, and hand it to a human. If review or testing reveals a bug, follow this sequence:</p><p>1. Record the raw evidence: command, exit code, test name, log excerpt, screenshot, accessibility hierarchy, or artifact path.<br>2. Classify the issue as application, specification, platform, harness environment, workflow, or test evidence.<br>3. Fix the application defect through the appropriate product workflow.<br>4. Re-run the affected tests and the relevant full gate.<br>5. Invoke `harness-retrospective` with the original failure and the repaired result.<br>6. Define the invariant that the harness should enforce in future.<br>7. Change the smallest authoritative harness artifact.<br>8. Add a regression fixture or contract test that proves the old failure is rejected.<br>9. Run the harness checks, record the retrospective, and return the result to human review.</p><p>This keeps application changes and process changes auditable.</p><h3>A Worked Example: Voice Recording Across Android API Levels</h3><p>Consider a voice-recording feature implemented with a minimum Android API of 24 and a target API of 34. Before implementation, the team should have started with a platform matrix. The matrix makes the runtime boundaries visible before code and tests begin:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*sEWYD4_WG-x1JjvAwC7pDw.png" /></figure><p>The initial implementation did not have this matrix. It was tested on a newer emulator and assumed that APIs available on the test device behaved the same on lower Android versions. Review then exposed several bugs:</p><ul><li>The code tried to use the on-device recognizer path below API 31 instead of selecting the documented fallback.</li><li>An OPUS request could fail on lower API/OEM combinations after recording had started, leaving AAC data with OPUS metadata or an incorrect file extension.</li><li>Newer foreground-service overloads and microphone permission behavior were not guarded for the minimum API.</li><li>The test suite reported the API-33 happy path but did not prove API-24 or API-31 runtime behavior.</li></ul><p>These are application defects, but the missing matrix is a harness problem. The product fix must correct API guards, codec fallback, metadata and file naming, and unavailable-transcription behavior. The harness fix must ensure that compatibility claims are not inferred from a single newer emulator.</p><p>The retrospective should record the matrix before the implementation stage and require each row to have an explicit result. For example:</p><blockquote>Every platform-bound feature must declare its minimum, target, and capability-boundary runtimes before implementation; each row must either have passing runtime evidence or be marked `Blocked`/`Revise`, and an unsupported API must exercise the declared fallback rather than silently pass.</blockquote><p>The corresponding verification plan should include:</p><ul><li>API 24 recording, permission, lifecycle, and codec-fallback coverage;</li><li>API 31 recognizer/model availability and audio-only fallback coverage;</li><li>API 33 source-fed recognition evidence on the available emulator;</li><li>API 34 target-level foreground-service and permission coverage;</li><li>a negative test proving that a missing runtime, model, or device is not reported as `Passed`.</li></ul><p>The important lesson is that a platform matrix is not planning paperwork added after a bug. It is the first test boundary for platform-dependent work. It tells the harness which claims require real devices, which behaviors are legitimate fallbacks, and when a green result is not evidence.</p><h3>The Invariant Is the Most Valuable Artifact</h3><p>A retrospective should produce one sentence that can be mechanically enforced. This is the invariant.</p><p>Weak retrospective conclusion:</p><blockquote>We should remember to test lower Android API versions next time.</blockquote><p>Strong retrospective conclusion:</p><blockquote>Every voice-recording feature must include runtime evidence for each declared Android API row, including the lower-API fallback, before the implementation stage can pass.</blockquote><p>Other useful invariants include:</p><ul><li>A required runtime check that was skipped cannot produce passing evidence.</li><li>Every interactive UI element has a stable accessibility identifier before UI verification passes.</li><li>A horizontal collection with a source-defined overflow behavior has a test that proves the content remains reachable on a constrained viewport.</li><li>A platform-adapted sheet, menu, or dialog has an explicit acceptance test for presentation and dismissal.</li><li>A test fixture must reach the state it claims to test; stale persisted data cannot be silently reused.</li><li>A <em>Pending</em>, <em>Unavailable</em>, or <em>Skipped</em> environment result is never equivalent to <em>Passed</em>.</li></ul><p>The invariant turns a lesson into a guardrail.</p><h3>Where to Fix the Gap</h3><p>Fix the highest authoritative layer that can enforce the invariant:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*c79sXQk98a103-2ZyxBy9Q.png" /></figure><p>Avoid adding reminders when a validator can enforce the rule. Human review is essential for judgment, but predictable omissions should become machine-checkable.</p><p>For example, if a feature plan declares whether it affects UI, the gate can require:</p><pre>{<br> &quot;affects_ui&quot;: true,<br> &quot;requires_visual_verification&quot;: true<br>}</pre><p>The validator can then reject a plan that changes UI but has no visual verification owner or no interaction evidence. The exact schema will vary by repository, but the principle is stable: make important claims explicit and validate them.</p><h3>What the harness-retrospective Skill Should Produce</h3><p>A useful retrospective is not a vague postmortem. It is a small, reviewable change set with evidence. The skill should produce an artifact such as:</p><pre>docs/changes/harness-retro-2026–08–26-voice-recording-platform-gap/<br>` - retrospective.md</pre><p>The record should contain:</p><ul><li><strong>Incident</strong>: what happened, where it was found, and which stage had passed.</li><li><strong>Classification</strong>: the primary root-cause category.</li><li><strong>Invariant</strong>: the one-sentence rule the harness must enforce.</li><li><strong>Root cause</strong>: the missing or ineffective workflow, skill, test, fixture, gate, or probe.</li><li><strong>Harness change</strong>: the exact files and behavior changed.</li><li><strong>Regression fixture</strong>: how the old false pass is now rejected.</li><li><strong>Verification</strong>: commands, exit codes, artifacts, and relevant excerpts.</li><li><strong>Routing</strong>: product or specification issues intentionally handled elsewhere.</li><li><strong>Remaining risk</strong>: what is still not proven.</li></ul><p>The artifact should quote paths and short excerpts so a reviewer can verify the claim without reconstructing the entire session.</p><h4>A Practical Prompt</h4><p>When a product defect has already been fixed, a focused prompt to the agent can look like this:</p><pre><br>Use $harness-retrospective to review the bug found during the completed feature loop.<br><br>Original symptom: [what failed]<br>Found during: [test, simulator review, or human review stage]<br>Product fix: [what was changed and how it now passes]<br>Evidence: [command, exit code, log, screenshot, or artifact path]<br><br>Determine whether this is a harness environment failure, workflow gap, or test evidence gap.<br>If it is, add the smallest enforceable invariant to the authoritative workflow, skill,<br>gate, template, validator, fixture, or contract test. Do not change product behavior<br>or acceptance requirements. Record the retrospective and expected negative-case evidence.</pre><p>This prompt gives the agent enough context to investigate while preserving the scope boundary.</p><h3>Improving Each Stage, Not Only the Final Test</h3><p>The strongest harnesses place feedback at every stage:</p><h4>Analysis</h4><p>Did the source map cover all behavior that affects users, including UI states, gestures, presentation, accessibility, and responsive bounds?</p><h4>Clarification</h4><p>Were open questions surfaced before the spec was written? Did the answers distinguish product decisions from platform adaptations?</p><h4>Planning</h4><p>Did every requirement map to an implementation file and a test? Did UI-affected work declare its verification owner and evidence?</p><h4>Test Migration</h4><p>Were tests written before production code? Did they encode the important Android edge cases rather than only happy-path rendering?</p><h4>Implementation</h4><p>Did the implementation preserve behavior while adapting only the platform-specific mechanics?</p><h4>Verification</h4><p>Did the tests run in the intended environment? Were seeded, empty, error, loading, overflow, navigation, and dismissal states actually exercised?</p><h4>Quality</h4><p>Did static checks and custom validators inspect the changed layer? Were warnings, skipped checks, and unavailable environments reported clearly?</p><h4>Human Review</h4><p>Could a reviewer verify the result from the recorded artifacts without trusting an agent’s summary?</p><p>A defect found at a later stage is a signal to inspect every earlier stage that could have prevented it.</p><h3>Do Not Turn the Harness into a Bureaucracy</h3><p>Retrospectives are valuable only when they improve signal. A few constraints keep them practical:</p><ul><li>Use the smallest raw evidence set that proves the issue.</li><li>Prefer one enforceable invariant over a page of reminders.</li><li>Change the authoritative source, not a downstream copy that will drift.</li><li>Add a focused negative-case test for every validator change.</li><li>Do not require screenshots when a deterministic structural test is sufficient.</li><li>Do require screenshots, accessibility inspection, or measured UI evidence when visual or platform presentation is part of the contract.</li><li>Preserve unrelated working-tree changes.</li><li>Never change lifecycle status or implementation authorization just to finish a retrospective.</li></ul><p>The harness should become more precise, not merely larger.</p><h3>A Definition of Done for Harness Retrospectives</h3><p>A retrospective is complete when:</p><ul><li>The root cause has one explicit classification.</li><li>The application bug and the harness gap are clearly separated.</li><li>The invariant is enforceable by a script, test, schema, or required artifact.</li><li>The authoritative workflow, skill, gate, template, or validator is minimally repaired.</li><li>A regression fixture proves the old false pass or omission is rejected.</li><li>Unavailable environments fail loudly instead of becoming green.</li><li>Relevant checks pass, including expected negative cases.</li><li>The retrospective records commands, results, paths, excerpts, and remaining risk.</li><li>The change is returned to human review.</li></ul><h3>Closing Thought</h3><p>A mature engineering harness does not claim that bugs will never happen. It learns from where the process was weak and converts that lesson into an executable constraint.</p><p>The most useful question after fixing a bug is not only:</p><blockquote>How do we repair this code?</blockquote><p>It is also:</p><blockquote>What should our harness have required, tested, or rejected so that this bug was discovered earlier and explained more clearly?</blockquote><p>That second question is where a delivery system begins to improve itself.</p><h3>Repository References</h3><p>- <em>harness-retrospective</em> skill (../../.agents/skills/harness-retrospective/SKILL.md)<br>- <em>voice-notes</em> platform capability matrix (../product/2026–08–14-voice-notes/platform-capability-matrix.md)<br>- <em>voice-notes</em> specification (../product/2026–08–14-voice-notes/spec.md)</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=b535915d0200" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Harness Engineering: Why UI Design Should Start Inside Harness Planning]]></title>
            <link>https://weidianhuang.medium.com/harness-engineering-why-ui-design-should-start-inside-harness-planning-ffe27b89412b?source=rss-865711e189d8------2</link>
            <guid isPermaLink="false">https://medium.com/p/ffe27b89412b</guid>
            <category><![CDATA[android]]></category>
            <category><![CDATA[harness-engineering]]></category>
            <category><![CDATA[ux-design]]></category>
            <category><![CDATA[ai]]></category>
            <category><![CDATA[figma]]></category>
            <dc:creator><![CDATA[Weidian Huang]]></dc:creator>
            <pubDate>Sun, 23 Aug 2026 12:49:37 GMT</pubDate>
            <atom:updated>2026-08-31T13:03:24.324Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*6mxZBhY8FPdI03pb8R2TMQ.png" /></figure><p>This article is part of my <strong>AI Coding Harness Engineering</strong> series, where I explore how to make AI coding agents more reliable for real software engineering work.</p><p>Rather than focusing only on model capability or prompt engineering, this series looks at the agentic system around the model: specifications, task decomposition, persistent context, verification gates, UI feedback, evaluator loops, and long-running workflows.</p><p><strong>Part 1 — </strong><a href="https://medium.com/@weidianhuang/harness-engineering-how-to-turn-ai-coding-agents-into-a-reliable-engineering-team-16af4f27775c"><strong>Why AI Coding Agents Need a Harness</strong></a><br>Why coding agents need an engineering harness around them, and the core failure modes the harness is designed to control.</p><p><strong>Part 2 — </strong><a href="https://medium.com/@weidianhuang/harness-engineering-how-to-set-up-an-android-agent-harness-b7154d9e3471"><strong>How to Set Up an Android Agent Harness</strong></a><br>A practical guide on using the Android agent harness in your project.</p><p><strong>Part 3 — </strong><a href="https://medium.com/@weidianhuang/harness-engineering-building-a-test-harness-that-can-prove-software-works-9c15ca65e8e5"><strong>Building a Test Harness That Can Prove Software Works</strong></a><strong><br></strong>A practical guide to tracing software requirements through tests, evidence, and review using an Android harness.</p><p><strong>Part 4 — </strong><a href="https://medium.com/@weidianhuang/harness-engineering-why-ui-design-should-start-inside-harness-planning-ffe27b89412b"><strong>Why UI Design Should Start Inside Harness Planning</strong></a><br>UX improves when design generation, harness planning, and runtime verification work together in one continuous loop.</p><p><strong>Part 5 — </strong><a href="https://medium.com/@weidianhuang/harness-engineering-building-coding-rules-into-an-ai-harness-1b259f69317a"><strong>Building Coding Rules Into an AI Harness</strong></a><strong><br></strong>Discover how an AI coding harness turns fragile rule-following into reliable quality by combining context-aware requirements, deterministic scripts, and independent evaluation.</p><p><strong>Part 6 — </strong><a href="https://medium.com/@weidianhuang/the-harness-matters-more-than-the-model-you-pick-ba5f8d66c238"><strong>Harnesses Raise the Floor and Lower the Blast Radius</strong></a><br>How engineering constraints affect smaller and larger models differently, and why stronger models still benefit from a well-designed harness.</p><p><strong>Part 7 — </strong><a href="https://medium.com/@weidianhuang/harness-engineering-building-a-retrospective-feedback-loop-b535915d0200"><strong>Building a Retrospective Feedback Loop</strong></a><strong><br></strong>How to build a continuous-improvement harness system around your project.</p><p>Source repositories:</p><ul><li><a href="https://github.com/hwdavr/NotesTakingApp/tree/master">NotesTakingApp</a></li><li><a href="https://github.com/hwdavr/android-agent-harness">android-agent-harness</a></li></ul><p><em>Why UI design, harness planning, MCP tools, and runtime verification should become one continuous workflow.</em></p><p>The traditional product development flow is familiar:</p><pre>Requirements → UX design → Ticket → Implementation → Test → Deploy</pre><p>The Product Owner creates requirements. UX creates the design. The Product Owner creates a ticket containing the requirements and design. Mobile Engineering implements the feature. QE tests it and collects evidence. Finally, the Product Owner verifies the test evidence.</p><p>This process provides accountability, but it was designed for a world where writing code was the slowest and most expensive part of development.</p><p>With agentic AI, that assumption is changing.</p><p>Claude Academy describes this shift as the move from a traditional linear SDLC to an AI-native SDLC: a continuous loop in which AI is embedded across planning, design, implementation, testing, deployment, and maintenance. It also highlights that once code generation becomes faster, the bottleneck moves to the stages around coding — especially planning, review, testing, and deployment. <a href="https://academy.claude.com/courses/ai-native-sdlc-playbook/introduction">Claude Academy</a></p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*5Smqd07RK3ST7gg_hwZ6NA.png" /><figcaption>AI-native SDLC from Claude Academy</figcaption></figure><p>Our harness environment applies the same idea specifically to mobile UI development.</p><h3>The biggest UI challenge is ambiguity</h3><p>Before implementation starts, many UI requirements are incomplete.</p><p>A feature request may say:</p><blockquote><em>“Add a Mermaid diagram block to the note editor.”</em></blockquote><p>That sounds simple, but it leaves many questions:</p><ul><li>Is the diagram shown inline or on a separate screen?</li><li>Does the block open in preview mode or edit mode?</li><li>How does the user edit Mermaid code?</li><li>What happens when the code is invalid?</li><li>Is there an empty state?</li><li>Can the diagram be zoomed or panned?</li><li>Is fullscreen supported?</li><li>What happens in read-only mode?</li><li>How does the screen behave in dark theme?</li><li>Which controls remain visible during errors?</li></ul><p>If these questions are not resolved before design generation, the design tool has to guess.</p><p>The result may be visually impressive but functionally inconsistent with the actual product requirement.</p><h3>The traditional handoff creates unnecessary friction</h3><p>The traditional process separates requirements and design into different handoffs:</p><pre>Product Requirements<br>        ↓<br>UX Design<br>        ↓<br>Ticket Creation<br>        ↓<br>Engineering<br>        ↓<br>QE<br>        ↓<br>Product Verification</pre><p>This makes ownership clear, but information is often lost between stages.</p><p>The Product Owner may describe the desired behavior in natural language. UX may interpret it visually. The ticket may contain only part of the interaction model. Engineering then fills in the gaps, often making decisions that should have been resolved earlier.</p><p>Claude Academy makes a similar observation: traditional requirements and design are separate phases, while an AI-native process compresses them into one working session guided by organizational standards and skills. <a href="https://academy.claude.com/courses/ai-native-sdlc-playbook/requirements-and-design">Requirements and design</a></p><p>This is especially important for UI work because visual design exposes ambiguity immediately.</p><h3>Why UI design should happen during harness planning</h3><p>The harness planning workflow is defined in:</p><pre>.agents/workflows/harness-planning.md</pre><p>The workflow creates a feature workspace containing artifacts such as:</p><pre>spec.md<br>design.md<br>design/mockup_*.png<br>feature_list.json<br>sprint-contract.md<br>progress.md</pre><p>The key idea is that design is created while the feature is still being clarified.</p><p>The planning flow becomes:</p><pre>Understand the requirement<br>        ↓<br>Identify open questions<br>        ↓<br>Generate UI alternatives<br>        ↓<br>Review the visual result<br>        ↓<br>Resolve product decisions<br>        ↓<br>Finalize specification and design<br>        ↓<br>Plan implementation slices</pre><p>This is more natural than writing a specification, leaving the planning workflow, generating a design in Figma or Pen.dev, and then returning to rewrite the plan.</p><p>The complex-feature planning workflow is defined in:</p><pre>.agents/workflows/harness-planning.md</pre><p>The planning workflow creates a stable feature workspace under:</p><pre>docs/product/&lt;date&gt;-&lt;feature-name&gt;/</pre><p>For UI work, the workspace normally contains:</p><pre>spec.md<br>design.md<br>design/mockup_*.png</pre><p>The visual design is developed while the requirements are still being clarified.</p><p>The natural flow becomes:</p><pre>Understand the requirement<br>        ↓<br>Identify open questions<br>        ↓<br>Generate UI alternatives<br>        ↓<br>Review the visual result<br>        ↓<br>Resolve product decisions<br>        ↓<br>Finalize the specification and design<br>        ↓<br>Plan implementation slices</pre><p>The design tool becomes part of the reasoning loop instead of a separate image generator.</p><h3>The UX design skill provides the design process</h3><p>The project UX design skill is:</p><pre>.agents/skills/ux-design/SKILL.md</pre><p>The project-wide design system is:</p><pre>docs/product/design_system.md</pre><p>The UX design skill requires the design system to be read before making visual decisions.</p><p>This prevents every feature from inventing its own visual language. New designs should reuse the project’s:</p><ul><li>semantic colors;</li><li>typography;</li><li>spacing scale;</li><li>Material 3 components;</li><li>bottom-sheet patterns;</li><li>accessibility rules;</li><li>minimum 48dp touch targets;</li><li>stable test tags.</li></ul><p>Figma or Pen.dev can generate the composition, but the harness provides the product context and visual constraints.</p><h3>Example: Mermaid Chart &amp; Preview</h3><p>A concrete example is the Mermaid Chart &amp; Preview feature.</p><p>Its feature workspace is:</p><pre>docs/product/2026-08-18-mermaid-chart-preview/</pre><p>The approved specification is:</p><pre>docs/product/2026-08-18-mermaid-chart-preview/spec.md</pre><p>The approved design is:</p><pre>docs/product/2026-08-18-mermaid-chart-preview/design.md</pre><p>The planning stage identified two major UI surfaces:</p><ol><li>An inline Mermaid diagram card inside the Note Editor.</li><li>A fullscreen diagram viewer.</li></ol><p>The approved preview mockup is:</p><pre>docs/product/2026-08-18-mermaid-chart-preview/design/mockup_mermaid_card_preview.png</pre><figure><img alt="" src="https://cdn-images-1.medium.com/max/768/1*GGfm1uhpo4DRIuLI1A0ISA.png" /></figure><p>It defines the default preview state:</p><ul><li>diagram title;</li><li>rendered Mermaid chart;</li><li>“Edit Code” action;</li><li>fullscreen action;</li><li>inline zoomable diagram canvas.</li></ul><p>The code editor mockup is:</p><pre>docs/product/2026-08-18-mermaid-chart-preview/design/mockup_mermaid_card_code_editor.png</pre><figure><img alt="" src="https://cdn-images-1.medium.com/max/768/1*ir1bLHp83xL3RQRkyu8V3g.png" /></figure><p>It clarifies that editing happens inside the same card. The editor includes:</p><ul><li>monospace Mermaid code;</li><li>“Flowchart” template chip;</li><li>“Sequence” template chip;</li><li>“Class” template chip;</li><li>“State” template chip;</li><li>syntax validation feedback;</li><li>“View Chart” action.</li></ul><p>The fullscreen mockup is:</p><pre>docs/product/2026-08-18-mermaid-chart-preview/design/mockup_mermaid_fullscreen_viewer.png</pre><figure><img alt="" src="https://cdn-images-1.medium.com/max/768/1*n-LMLCL8C7ex5xXeOj9kEw.png" /></figure><p>It defines:</p><ul><li>an edge-to-edge diagram canvas;</li><li>zoom controls;</li><li>“Fit to Screen”;</li><li>copy code;</li><li>SVG export or sharing;</li><li>a back action to return to the editor.</li></ul><p>These mockups helped resolve important product decisions before implementation:</p><ul><li>preview is the default mode;</li><li>code editing happens inside the card;</li><li>invalid syntax produces an inline error;</li><li>fullscreen is a separate viewer;</li><li>read-only notes can still inspect diagrams;</li><li>zoom controls must support both gestures and accessibility;</li><li>Mermaid rendering must work offline.</li></ul><p>Without the visual design, many of these requirements could have remained implicit.</p><h3>The design becomes part of the implementation contract</h3><p>The Mermaid design defines stable visual test tags such as:</p><pre>editor_mermaid_block_{id}<br>editor_mermaid_toggle_mode_{id}<br>editor_mermaid_preview_canvas_{id}<br>editor_mermaid_code_editor_{id}<br>editor_mermaid_fullscreen_btn_{id}<br>fullscreen_diagram_canvas<br>fullscreen_zoom_controls</pre><p>It also defines measurable reference relationships:</p><pre>card.left == content.left + 16dp<br>card.right == content.right - 16dp<br>toggleBtn.centerY == title.centerY<br>editor.padding == 12dp</pre><p>This is more precise than saying that the card should “look balanced.”</p><p>The design is now connected to implementation, testing, and later visual verification.</p><h3>How the harness verifies the design</h3><p>The UI verification skill is:</p><pre>.agents/skills/ui-verification/SKILL.md</pre><p>The verification process is layered:</p><ol><li>Build and static checks.</li><li>Instrumented Android tests.</li><li>Screenshot capture from the active test window.</li><li>Screenshot normalization.</li><li>Area-of-interest selection.</li><li>Region decomposition.</li><li>Structural bounds verification.</li><li>Dynamic-content masking.</li><li>Perceptual comparison.</li><li>Defect classification and final evaluation.</li></ol><p>For Mermaid, runtime visual evidence is stored under:</p><pre>docs/product/2026-08-18-mermaid-chart-preview/visual_evidence/</pre><p>The captured screenshots include:</p><pre>visual_evidence/mermaid_card_preview.png<br>visual_evidence/mermaid_card_code_editor.png<br>visual_evidence/mermaid_fullscreen_viewer.png</pre><p>The reference-anchor report is:</p><pre>docs/product/2026-08-18-mermaid-chart-preview/visual_evidence/reference-anchor-verification.md</pre><p>It verifies relationships such as:</p><pre>canvasBounds.width == screenBounds.width - 32dp<br>editorBounds.width == screenBounds.width - 32dp<br>canvasBounds.width == screenBounds.width</pre><p>The first two checks verify that the inline preview and code editor respect the editor’s 16dp horizontal margins.</p><p>The third verifies that the fullscreen viewer reaches the screen edges.</p><h3>The evidence contract prevents false confidence</h3><p>The visual evidence contract is enforced by:</p><pre>harness/scripts/check-visual-evidence-contract.sh</pre><p>The report structure is defined by:</p><pre>harness/templates/ui-verification-template.json</pre><p>The contract verifies that:</p><ul><li>the visual test is declared in the sprint contract;</li><li>the test method actually ran;</li><li>connected Android evidence exists;</li><li>the screenshot is non-empty;</li><li>the approved reference exists;</li><li>the runtime test uses a visual test tag;</li><li>a concrete bounds relationship is recorded;</li><li>the evidence result is PASS.</li></ul><p>Screenshots must be captured inside the active test after Compose reaches an idle state. They are then pulled from the emulator.</p><p>This prevents a common false positive: taking a screenshot after the test Activity has already closed and accidentally capturing the device home screen.</p><h3>Why this is faster</h3><p>At first, generating UI during planning may appear slower because it adds design work before implementation.</p><p>In practice, it is often faster because it reduces rework.</p><p>Planning-stage design helps us:</p><ul><li>discover missing states;</li><li>resolve interaction ambiguity;</li><li>identify reusable components;</li><li>define test tags early;</li><li>establish visual anchors;</li><li>create better acceptance tests;</li><li>divide the feature into meaningful slices;</li><li>identify which slice owns final visual verification.</li></ul><p>The alternative is to implement first and discover these questions during review.</p><p>That is usually much more expensive.</p><h3>Loop engineering for UI</h3><p>The UI loop is:</p><pre>Clarify<br>  ↓<br>Design<br>  ↓<br>Approve<br>  ↓<br>Implement<br>  ↓<br>Run on Android<br>  ↓<br>Compare against the design<br>  ↓<br>Fix<br>  ↓<br>Verify again</pre><p>Figma and Pen.dev make the design step faster.</p><p>MCP servers make those tools available inside the agent workflow.</p><p>The harness makes sure the design remains connected to requirements, implementation, and evidence.</p><p>The goal is not simply to generate a beautiful screen.</p><p>The goal is to generate the right screen, for the right product reason, with a verification path that can prove it.</p><h3>Conclusion</h3><p>Figma and Pen.dev can produce excellent UI results through MCP servers. But the most important factor is not only which design tool we use.</p><p>It is when we use it.</p><p>When UI design is generated inside harness planning:</p><ul><li>open questions are discovered earlier;</li><li>visual alternatives clarify the requirement;</li><li>specification and design evolve together;</li><li>implementation is based on an approved visual target;</li><li>acceptance tests include visual relationships;</li><li>runtime verification has a clear reference;</li><li>the development loop remains continuous.</li></ul><p>The design tool accelerates visual exploration.</p><p>The harness preserves product intent.</p><p>And the verification system connects the final Android UI back to the original requirement.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=ffe27b89412b" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Harness Engineering: Building a Test Harness That Can Prove Software Works]]></title>
            <link>https://weidianhuang.medium.com/harness-engineering-building-a-test-harness-that-can-prove-software-works-9c15ca65e8e5?source=rss-865711e189d8------2</link>
            <guid isPermaLink="false">https://medium.com/p/9c15ca65e8e5</guid>
            <category><![CDATA[android-app-development]]></category>
            <category><![CDATA[software-testing]]></category>
            <category><![CDATA[harness-engineering]]></category>
            <category><![CDATA[android]]></category>
            <category><![CDATA[ai]]></category>
            <dc:creator><![CDATA[Weidian Huang]]></dc:creator>
            <pubDate>Sat, 22 Aug 2026 10:49:45 GMT</pubDate>
            <atom:updated>2026-08-31T13:03:05.266Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*ElbySInde3d1qQM2dUd_8w.png" /></figure><p>This article is part of my <strong>AI Coding Harness Engineering</strong> series, where I explore how to make AI coding agents more reliable for real software engineering work.</p><p>Rather than focusing only on model capability or prompt engineering, this series looks at the agentic system around the model: specifications, task decomposition, persistent context, verification gates, UI feedback, evaluator loops, and long-running workflows.</p><p><strong>Part 1 — </strong><a href="https://medium.com/@weidianhuang/harness-engineering-how-to-turn-ai-coding-agents-into-a-reliable-engineering-team-16af4f27775c"><strong>Why AI Coding Agents Need a Harness</strong></a><br>Why coding agents need an engineering harness around them, and the core failure modes the harness is designed to control.</p><p><strong>Part 2 — </strong><a href="https://medium.com/@weidianhuang/harness-engineering-how-to-set-up-an-android-agent-harness-b7154d9e3471"><strong>How to Set Up an Android Agent Harness</strong></a><br>A practical guide on using the Android agent harness in your project.</p><p><strong>Part 3 — </strong><a href="https://medium.com/@weidianhuang/harness-engineering-building-a-test-harness-that-can-prove-software-works-9c15ca65e8e5"><strong>Building a Test Harness That Can Prove Software Works</strong></a><strong><br></strong>A practical guide to tracing software requirements through tests, evidence, and review using an Android harness.</p><p><strong>Part 4 — </strong><a href="https://medium.com/@weidianhuang/harness-engineering-why-ui-design-should-start-inside-harness-planning-ffe27b89412b"><strong>Why UI Design Should Start Inside Harness Planning</strong></a><br>UX improves when design generation, harness planning, and runtime verification work together in one continuous loop.</p><p><strong>Part 5 — </strong><a href="https://medium.com/@weidianhuang/harness-engineering-building-coding-rules-into-an-ai-harness-1b259f69317a"><strong>Building Coding Rules Into an AI Harness</strong></a><strong><br></strong>Discover how an AI coding harness turns fragile rule-following into reliable quality by combining context-aware requirements, deterministic scripts, and independent evaluation.</p><p><strong>Part 6 — </strong><a href="https://medium.com/@weidianhuang/the-harness-matters-more-than-the-model-you-pick-ba5f8d66c238"><strong>Harnesses Raise the Floor and Lower the Blast Radius</strong></a><br>How engineering constraints affect smaller and larger models differently, and why stronger models still benefit from a well-designed harness.</p><p><strong>Part 7 — </strong><a href="https://medium.com/@weidianhuang/harness-engineering-building-a-retrospective-feedback-loop-b535915d0200"><strong>Building a Retrospective Feedback Loop</strong></a><strong><br></strong>How to build a continuous-improvement harness system around your project.</p><p>Source repositories:</p><ul><li><a href="https://github.com/hwdavr/NotesTakingApp/tree/master">NotesTakingApp</a></li><li><a href="https://github.com/hwdavr/android-agent-harness">android-agent-harness</a></li></ul><p>When a project becomes large enough, “we have tests” is no longer a meaningful quality statement.</p><p>The more important questions are:</p><ul><li>Which functional requirements are tested?</li><li>Which acceptance criteria are verified?</li><li>Does each test exercise a real production path?</li><li>Are failures, fallbacks, permissions, lifecycle events, and visual states covered?</li><li>Can another engineer prove why a feature is considered complete?</li></ul><p>In my Android notes application, I use a harness environment to answer these questions systematically.</p><p>The goal is not simply to increase the number of tests. The goal is to connect requirements to implementation, tests, evidence, and review.</p><h3>The testing pipeline</h3><p>The central flow in the harness is:</p><pre>Requirement<br>    ↓<br>Feature specification<br>    ↓<br>Acceptance criteria<br>    ↓<br>Sprint contract<br>    ↓<br>Test cases<br>    ↓<br>Verification commands<br>    ↓<br>Evidence<br>    ↓<br>Test review and code review<br>    ↓<br>Lifecycle transition</pre><p>The project rules are defined in AGENTS.md, while the Android architecture rules are documented in .agents/rules/android-architecture.md and the testing strategy in .agents/rules/testing-strategy.md.</p><p>Every stage has a defined artifact and a gate. This prevents testing from becoming an activity that happens only at the end of development.</p><h3>Start with functional requirements and acceptance criteria</h3><p>The first step is to define the behavior precisely.</p><p>For example, a Code Block feature may contain requirements such as:</p><ul><li>The note document must support a CodeBlock model.</li><li>The Basic Blocks panel must contain an Advanced section.</li><li>Selecting the Code tile must insert a block.</li><li>The language selector must update syntax highlighting.</li><li>Copying the block must place the exact text into the system clipboard.</li><li>Read-only notes must allow copying but prevent editing.</li><li>Markdown export must use fenced code blocks.</li></ul><p>These requirements are converted into acceptance criteria using a Given/When/Then structure.</p><pre>Given an editable note,<br>When the user selects the Code tile,<br>Then a Code Block is inserted, the panel collapses,<br>and the document is automatically saved.</pre><p>The feature specification and acceptance criteria are stored in a feature workspace such as:</p><pre>docs/product/2026-08-18-code-block/spec.md</pre><p>Vague requirements produce vague tests. A test named testCodeBlockWorks does not tell us which behavior is covered.</p><p>A better test is:</p><pre>testInsertCodeBlockFromBasicBlocksPanel</pre><p>The test name, production action, and expected outcome all describe the same behavior.</p><h3>Build a requirement-to-test traceability matrix</h3><p>The most important testing artifact in the harness is the traceability matrix.</p><p>Each functional requirement, acceptance criterion, and documented edge case receives its own row in the test review report:</p><pre>docs/product/&lt;feature&gt;/test_review_&lt;feature-id&gt;.md</pre><p>Each row identifies:</p><iframe src="https://cdn.embedly.com/widgets/media.html?src=https%3A%2F%2Fdatawrapper.dwcdn.net%2F04Bgb%2F1%2F&amp;display_name=Datawrapper&amp;url=https%3A%2F%2Fdatawrapper.dwcdn.net%2F04Bgb%2F1%2F&amp;image=https%3A%2F%2Fdatawrapper.dwcdn.net%2F04Bgb%2Fplain-s.png%3Fv%3D1&amp;type=text%2Fhtml&amp;schema=dwcdn" width="600" height="308" frameborder="0" scrolling="no"><a href="https://medium.com/media/b9eaca74c7b702eb35c07cfea6991239/href">https://medium.com/media/b9eaca74c7b702eb35c07cfea6991239/href</a></iframe><p>This prevents a common mistake: assuming one broad test covers several different outcomes.</p><p>If a requirement contains both a success path and a fallback path, the matrix should expose them separately.</p><p>For example:</p><pre>Serialize a document successfully<br>Deserialize unknown fields safely<br>Fallback to Plain Text when language is missing<br>Preserve the code content</pre><p>Each outcome must have a test or be explicitly marked as requiring revision.</p><h3>Use the lowest reliable test layer</h3><p>The project follows the test pyramid defined in .agents/rules/testing-strategy.md:</p><pre>Instrumented UI tests<br>        ↑<br>JVM integration tests<br>        ↑<br>JVM unit tests</pre><p>The rule is simple: start at the lowest layer that provides enough confidence.</p><h3>Unit tests</h3><p>Unit tests live under:</p><pre>app/src/test/</pre><p>They cover:</p><ul><li>Domain use cases</li><li>ViewModel state transitions</li><li>Mappers</li><li>Reducers</li><li>Formatters</li><li>Syntax highlighting</li><li>Serialization</li><li>Error and fallback logic</li></ul><p>For example:</p><pre>app/src/test/java/com/example/notesapp/ui/editor/components/CodeSyntaxHighlighterTest.kt</pre><p>verifies language tokenization and dynamic line numbers without requiring an Android device.</p><p>New ViewModels and domain use cases have a 90% line coverage target.</p><h3>JVM integration tests</h3><p>Integration tests also run on the JVM, but connect multiple application layers:</p><pre>Repository → Use Case → ViewModel → UiState</pre><p>They verify persistence, auto-save behavior, API mapping, retry behavior, and error states.</p><p>API-related tests use shared JSON scenarios under:</p><pre>sharedContracts/test-scenarios/</pre><p>This avoids creating inconsistent fake payloads in individual test files.</p><h3>Instrumented UI tests</h3><p>Instrumented tests live under:</p><pre>app/src/androidTest/</pre><p>They are used when Android runtime behavior matters:</p><ul><li>Compose rendering</li><li>User gestures</li><li>Navigation</li><li>Clipboard interaction</li><li>Lifecycle behavior</li><li>Android services</li><li>Runtime permissions</li><li>Platform APIs</li></ul><p>The project targets an Android emulator and avoids timing-based patterns such as Thread.sleep. Compose tests use idling mechanisms such as waitForIdle() and waitUntil().</p><h3>Visual verification tests</h3><p>Visual tests are specialized instrumented tests. They capture screenshots while the test Activity is actively rendering.</p><p>The harness requires visual evidence to connect:</p><ul><li>An approved design asset</li><li>A runtime testTag</li><li>A measured layout relationship</li><li>A captured screenshot</li></ul><p>The contract is enforced by:</p><pre>harness/scripts/check-visual-evidence-contract.sh</pre><p>This is stronger than simply saying that a screenshot “looks correct.”</p><h3>Platform boundary tests</h3><p>Some behaviors cannot be proven by JVM tests or fake implementations.</p><p>Voice recording is one example because it depends on Android services, audio APIs, permissions, device behavior, and platform capabilities.</p><p>Platform-bound features require:</p><ul><li>A platform capability matrix</li><li>A real instrumented boundary test</li><li>A declared runtime environment</li><li>A successful connected test command</li><li>Explicit failure when the environment is unavailable</li></ul><p>The contract is validated by:</p><pre>harness/scripts/check-platform-evidence.sh</pre><p>A fake recognizer or manually emitted callback may supplement coverage, but cannot prove that the shipped Android integration works.</p><p>Unavailable runtime evidence is not passing evidence.</p><h3>Regression tests</h3><p>Bug fixes require a reproduction test.</p><p>The process is:</p><pre>Write failing reproduction test<br>        ↓<br>Fix the production bug<br>        ↓<br>Run the test again<br>        ↓<br>Confirm the regression is prevented</pre><p>This ensures the fix addresses a demonstrated failure.</p><h3>Coverage is necessary, but not sufficient</h3><p>The project requires at least 80% overall line coverage, verified with:</p><pre>./gradlew koverLog</pre><p>However, coverage percentage alone can be misleading. A project can achieve high coverage by testing simple getters while leaving important behavior branches unverified.</p><p>That is why the test review examines both coverage and behavior.</p><p>Compose screens and components are excluded from Kover because line coverage is not a meaningful measure of visual behavior. Their behavior is verified through instrumented UI and visual tests.</p><p>The principle is:</p><pre>Use coverage to find untested code.<br>Use behavior assertions to prove requirements.</pre><h3>Harness stages turn testing into a controlled process</h3><p>Each complex feature has a dated workspace under:</p><pre>docs/product/&lt;YYYY-MM-DD&gt;-&lt;feature-name&gt;/</pre><p>The workspace contains the source of truth for the feature:</p><ul><li>spec.md</li><li>design.md</li><li>feature_list.json</li><li>sprint-contract.md</li><li>Slice summaries</li><li>Test review</li><li>Code review</li><li>Evaluator rubric</li><li>Runtime evidence</li><li>Session handoff</li></ul><p>The harness planning workflow is defined in:</p><pre>.agents/workflows/harness-planning.md</pre><p>Implementation follows:</p><pre>.agents/workflows/harness-generator.md</pre><p>The lifecycle is tracked in docs/product/product.md:</p><pre>Planning<br>   ↓<br>Awaiting specification approval<br>   ↓<br>Awaiting implementation approval<br>   ↓<br>In Progress<br>   ↓<br>To be reviewed<br>   ↓<br>To be fixed, if review fails<br>   ↓<br>To be human reviewed<br>   ↓<br>Complete</pre><p>The lifecycle is validated with:</p><pre>harness/scripts/check-feature-lifecycle.sh</pre><p>A feature cannot move forward simply because a file was created.</p><h3>Passing requires objective evidence</h3><p>Each user story contains acceptance-test commands in sprint-contract.md.</p><p>The feature status can change to passing only when every required command succeeds.</p><p>Evidence records:</p><ul><li>Test ID</li><li>Exact command</li><li>Exit code</li><li>Timestamp</li><li>Result</li><li>Verification notes</li></ul><p>For example:</p><pre>{<br>  &quot;test_id&quot;: &quot;TC-US-2-06&quot;,<br>  &quot;exit_code&quot;: 0,<br>  &quot;result&quot;: &quot;PASS&quot;,<br>  &quot;notes&quot;: &quot;Clipboard contains the exact code string.&quot;<br>}</pre><p>This prevents a test from being considered complete merely because someone remembers that it passed earlier.</p><h3>Testing is reviewed separately from implementation</h3><p>The testing stage creates tests and runs them. It does not decide whether those tests are good enough.</p><p>That responsibility belongs to the android-test-review skill:</p><pre>.agents/skills/android-test-review/SKILL.md</pre><p>The reviewer checks:</p><ul><li>Does every requirement have a traceability row?</li><li>Does every acceptance criterion have a mapped test?</li><li>Does the test exercise a real production trigger?</li><li>Does it assert an observable result?</li><li>Are error and fallback paths covered?</li><li>Are API tests using shared scenarios?</li><li>Are platform tests using real boundaries?</li><li>Are visual tests capturing active runtime state?</li><li>Is coverage concentrated on meaningful behavior?</li><li>Are timing assumptions avoided?</li></ul><p>A test that clicks a button but only verifies that a callback was invoked may be rejected if the real requirement is a state change or visible UI outcome.</p><h3>Code review and evaluator review provide another safety layer</h3><p>After test review, the harness runs code review and runtime verification according to:</p><pre>.agents/workflows/harness-evaluation.md</pre><p>The evaluator checks:</p><ul><li>Correctness</li><li>Verification evidence</li><li>Scope discipline</li><li>Reliability</li><li>Maintainability</li><li>Handoff readiness</li><li>Code and test quality</li></ul><p>If the final score is below 5.0, the feature moves to To be fixed. The fix workflow is then applied using:</p><pre>.agents/workflows/harness-fix.md</pre><p>Every finding must be resolved in the review reports themselves. The feature must be re-tested, re-reviewed, and re-verified before returning to human review.</p><h3>The main lesson</h3><p>A strong testing environment is not just a collection of test files.</p><p>It is a system that answers four questions:</p><ol><li>What behavior is required?</li><li>Which test proves that behavior?</li><li>What evidence shows that the test passed?</li><li>Who reviews whether the evidence is trustworthy?</li></ol><p>The harness makes those answers explicit.</p><p>Functional requirements become acceptance criteria. Acceptance criteria become test cases. Test cases become executable commands. Commands produce evidence. Evidence is reviewed independently. Lifecycle state changes only after the required gates pass.</p><p>That is how testing moves from “we ran some tests” to a defensible engineering process.</p><p>The goal is not to claim that software has no bugs.</p><p>The goal is to make every quality claim traceable, repeatable, and reviewable.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=9c15ca65e8e5" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Harness Engineering: How to Set Up an Android Agent Harness]]></title>
            <link>https://weidianhuang.medium.com/harness-engineering-how-to-set-up-an-android-agent-harness-b7154d9e3471?source=rss-865711e189d8------2</link>
            <guid isPermaLink="false">https://medium.com/p/b7154d9e3471</guid>
            <category><![CDATA[ai]]></category>
            <category><![CDATA[ai-coding]]></category>
            <category><![CDATA[harness-engineering]]></category>
            <category><![CDATA[ai-agent]]></category>
            <category><![CDATA[android]]></category>
            <dc:creator><![CDATA[Weidian Huang]]></dc:creator>
            <pubDate>Sat, 22 Aug 2026 10:36:59 GMT</pubDate>
            <atom:updated>2026-08-31T13:02:51.312Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*rOUrFmOztLAIzluK7p9Mog.png" /></figure><p>This article is part of my <strong>AI Coding Harness Engineering</strong> series, where I explore how to make AI coding agents more reliable for real software engineering work.</p><p>Rather than focusing only on model capability or prompt engineering, this series looks at the agentic system around the model: specifications, task decomposition, persistent context, verification gates, UI feedback, evaluator loops, and long-running workflows.</p><p><strong>Part 1 — </strong><a href="https://medium.com/@weidianhuang/harness-engineering-how-to-turn-ai-coding-agents-into-a-reliable-engineering-team-16af4f27775c"><strong>Why AI Coding Agents Need a Harness</strong></a><br>Why coding agents need an engineering harness around them, and the core failure modes the harness is designed to control.</p><p><strong>Part 2 — </strong><a href="https://medium.com/@weidianhuang/harness-engineering-how-to-set-up-an-android-agent-harness-b7154d9e3471"><strong>How to Set Up an Android Agent Harness</strong></a><br>A practical guide on using the Android agent harness in your project.</p><p><strong>Part 3 — </strong><a href="https://medium.com/@weidianhuang/harness-engineering-building-a-test-harness-that-can-prove-software-works-9c15ca65e8e5"><strong>Building a Test Harness That Can Prove Software Works</strong></a><strong><br></strong>A practical guide to tracing software requirements through tests, evidence, and review using an Android harness.</p><p><strong>Part 4 — </strong><a href="https://medium.com/@weidianhuang/harness-engineering-why-ui-design-should-start-inside-harness-planning-ffe27b89412b"><strong>Why UI Design Should Start Inside Harness Planning</strong></a><br>UX improves when design generation, harness planning, and runtime verification work together in one continuous loop.</p><p><strong>Part 5 — </strong><a href="https://medium.com/@weidianhuang/harness-engineering-building-coding-rules-into-an-ai-harness-1b259f69317a"><strong>Building Coding Rules Into an AI Harness</strong></a><strong><br></strong>Discover how an AI coding harness turns fragile rule-following into reliable quality by combining context-aware requirements, deterministic scripts, and independent evaluation.</p><p><strong>Part 6 — </strong><a href="https://medium.com/@weidianhuang/the-harness-matters-more-than-the-model-you-pick-ba5f8d66c238"><strong>Harnesses Raise the Floor and Lower the Blast Radius</strong></a><br>How engineering constraints affect smaller and larger models differently, and why stronger models still benefit from a well-designed harness.</p><p><strong>Part 7 — </strong><a href="https://medium.com/@weidianhuang/harness-engineering-building-a-retrospective-feedback-loop-b535915d0200"><strong>Building a Retrospective Feedback Loop</strong></a><strong><br></strong>How to build a continuous-improvement harness system around your project.</p><p>Source repositories:</p><ul><li><a href="https://github.com/hwdavr/NotesTakingApp/tree/master">NotesTakingApp</a></li><li><a href="https://github.com/hwdavr/android-agent-harness">android-agent-harness</a></li></ul><p>This is a practical guide to using the Android agent harness in my repository: <a href="https://github.com/hwdavr/NotesTakingApp/tree/master">NotesTakingApp</a>.<br>The reusable harness itself lives in the <a href="https://github.com/hwdavr/android-agent-harness">android-agent-harness</a> submodule repository.</p><p>The harness is a collection of context files, workflows, skills, templates, scripts, and evidence artifacts. Its purpose is to make a manual AI-assisted development session predictable: load the right context, run the right workflow, stop at the right approval gates, and leave enough evidence for the next session.</p><p><strong>## 1. Set up the repository once</strong></p><p>The harness is already wired into NotesTakingApp. The harness command path is harness/, backed by the .harness submodule.</p><p>If you are working on the example app, clone NotesTakingApp and initialize its submodule:</p><pre>git clone https://github.com/hwdavr/NotesTakingApp.git<br>cd NotesTakingApp<br>git submodule update - init - recursive</pre><p>If you are starting a new project, use the harness repository as the starting template. Clone or download <a href="https://github.com/hwdavr/android-agent-harness">android-agent-harness</a>, copy its complete content into the root of your new project, and create the Android project from that prepared directory. Copy hidden files as well as visible files; the agent rules, workflows, skills, templates, and scripts are part of the setup.</p><p>The resulting project should keep the harness structure at the repository root:</p><pre>AGENTS.md<br>.agents/<br>harness/</pre><p>Then add the Android application module and project-specific files alongside the harness. Update AGENTS.md with the new app’s stack, modules, architecture rules, build commands, and test strategy before asking an agent to implement a feature.</p><p>The exact setup sequence for a new project is:</p><p>1. Copy the content of android-agent-harness into the new project directory.</p><p>2. Create or initialize the Android Studio project in that directory.</p><p>3. Add the app module, source code, Gradle files, and any shared contracts.</p><p>4. Replace the example-specific context in AGENTS.md with the new project context.</p><p>5. Run the harness checks before starting feature work.</p><p>For Compose and platform-bound work, keep an emulator available. The project convention is emulator-5554.</p><p><strong>## 2. Create the product and design foundation for a new project</strong></p><p>If this is a new product, do not begin feature implementation with an empty product document and an undefined visual language. First create two files under docs/product/:</p><pre>docs/product/product.md<br>docs/product/design_system.md</pre><p>Use AI to turn the product idea into a first product document. The goal is not to let AI invent a finished roadmap without review. The goal is to make the product assumptions visible so you can correct them before implementation.</p><p>Use a prompt like this:</p><pre>[Describe the product idea with enough detail.]<br><br>For this new Android product, ask me the essential product questions, then<br>create docs/product/product.md for:<br>- vision and target users;<br>- first-release scope and non-goals;<br>- current capabilities and roadmap;<br>- the Harness Feature Tracker.<br>Do not write application code or claim unshipped features are complete. Stop<br>and present product.md for approval.</pre><p>Review product.md and correct the product language before moving to design. It becomes the product-level context that future planning prompts can read.</p><p>Next, use Pen.dev to design the landing screen. Choose the design style deliberately: for example, minimal editorial, warm and friendly, bold and playful, or calm and professional. The landing screen should establish the product’s visual direction without trying to design every feature at once.</p><p>Once the landing screen is approved in Pen.dev, ask AI to extract a reusable design system from it:</p><pre>Using this approved Pen.dev landing-screen reference:<br>[Paste the Pen.dev link or attach the export.]<br><br>Print out the design system with reusable principles, color and<br>typography tokens, spacing and component rules, states, and accessibility<br>requirements.</pre><p>The order matters:</p><p>1. Define the product direction in product.md.</p><p>2. Choose the visual direction in Pen.dev.</p><p>3. Derive design_system.md from the approved visual reference.</p><p>4. Approve both files before planning the first feature.</p><p>For every later UI feature, the harness should load docs/product/design_system.md first. A feature-specific mockup can add detail, but it should not silently redefine the product’s visual language.</p><p><strong>## 3. Choose the workflow before writing a prompt</strong></p><p>Use the workflow file as the contract for the session.</p><iframe src="https://cdn.embedly.com/widgets/media.html?src=https%3A%2F%2Fdatawrapper.dwcdn.net%2Fa4IXQ%2F1%2F&amp;display_name=Datawrapper&amp;url=https%3A%2F%2Fdatawrapper.dwcdn.net%2Fa4IXQ%2F1%2F&amp;image=https%3A%2F%2Fdatawrapper.dwcdn.net%2Fa4IXQ%2Fplain-s.png%3Fv%3D1&amp;type=text%2Fhtml&amp;schema=dwcdn" width="600" height="485" frameborder="0" scrolling="no"><a href="https://medium.com/media/94402321d5cba32dc5c1412e234b642d/href">https://medium.com/media/94402321d5cba32dc5c1412e234b642d/href</a></iframe><p>A common mistake is to use the Generator workflow for a vague idea. Use harness-planning first when the scope is not yet clear.</p><p>Another common mistake is to use the full harness for a one-line change. Use feature-delivery for a small enhancement, but still respect its requirement and implementation-plan approval gates.</p><p><strong>## 4. Start every session with Load context</strong></p><p>Before every session, send this prompt first:</p><pre>Load context.</pre><p>This invokes the context-management skill. It loads the project rules, the matching workflow, the current-stage skills, and the relevant source context. For an approved complex feature, it also orients the agent to the next task in the product backlog through the active product workspace and feature tracker. Do this every time you start a new coding session.</p><p><strong>## 5. Prompt the complex-feature planning workflow</strong></p><p>Use this path when the feature needs several files or logical areas, introduces a new screen or flow, or needs to be split into independently deliverable slices.</p><p>First, prompt the Planner:</p><pre>Load context<br>Use harness-planning workflow for this task.<br>Feature request:<br>[Describe the user, goal, expected behavior, and known constraints.]</pre><p>The expected result is:</p><pre>docs/product/&lt;YYYY-MM-DD&gt;-&lt;feature-short-name&gt;/spec.md<br>docs/product/&lt;YYYY-MM-DD&gt;-&lt;feature-short-name&gt;/design.md<br>docs/product/&lt;YYYY-MM-DD&gt;-&lt;feature-short-name&gt;/design/mockup_*.png</pre><p>The design files are conditional. A logic-only feature does not need mockups.</p><p>Do not reply with “approved” until you have read the specification. The approval should mean that the user behavior, scope, persistence, errors, and verification expectations are understood.</p><p><strong>## 6. Approve the specification, then prompt slice planning</strong></p><p>After reviewing the specification, use a short approval prompt:</p><pre>Approved, continue with slice planning.</pre><p>Review the generated files:</p><pre>docs/product/&lt;feature-workspace&gt;/feature_list.json<br>docs/product/&lt;feature-workspace&gt;/progress.md<br>docs/product/&lt;feature-workspace&gt;/sprint-contract.md</pre><p>Approve only when the slice boundaries, acceptance tests, and out-of-scope items make sense:</p><pre>Approved, continue with implementation.<br>Use harness-generator workflow. Implement one approved slice.</pre><p><strong>## 7. Prompt the Generator to implement one slice</strong></p><p>To better control the context window, create a new session for each slice.</p><p>Start the session with:</p><pre>Load context.<br>Use harness-generator workflow to implement the next slice.</pre><p><strong>## 8. Prompt the Generator after a failed gate</strong></p><p>Do not ask for a broad rewrite when one command fails. Send the failure back with the exact command:</p><pre>Load context.<br>This gate failed:<br>[Paste the exact command]<br>Failure:<br>[Paste the relevant output]<br>Use harness-generator workflow to diagnose and apply the smallest root-cause fix.<br>Do not add suppressions or weaken tests. Re-run the failed gate, update evidence,<br>and report the result.</pre><p>For a test failure, ask the agent to preserve the failing test as the regression proof. For a visual failure, point it back to the approved mockup and design-system tokens rather than asking it to “make it look better.”</p><p><strong>## 9. Prompt the Evaluator separately</strong></p><p>When every slice is passing and the Generator has moved the feature to To be reviewed, start an independent review with a new session:</p><pre>Load context.<br>Use harness-evaluation workflow. Review the active feature independently.</pre><p>The Evaluator is not a second implementation prompt. It is a challenge prompt. Its job is to find incomplete behavior, weak assertions, architecture violations, missing evidence, and claims that are not supported by a real command result.</p><p><strong>## 10. Prompt the fix workflow when review finds issues</strong></p><p>If the Evaluator moves the feature to To be fixed, use a targeted fix prompt:</p><pre>Load context.<br>Use harness-fix workflow. Resolve every review finding one at a time.</pre><p><strong>## 11. Prompt the small-feature workflow</strong></p><p>For a small enhancement that does not need a multi-slice workspace:</p><pre>Load context.<br>Use feature-delivery workflow to implement this feature.<br>[Describe the feature.]</pre><p>The important distinction is that a small task still requires a plan approval. “Small” does not mean “skip the workflow.”</p><p><strong>## 12. Prompt the bug-fixing workflow</strong></p><p>For a crash, regression, or unexpected behavior, start with reproduction rather than a fix:</p><pre>Load context.<br>Use bug-fixing workflow to fix the below bug.<br>Bug:<br>[Describe expected behavior and actual behavior.]</pre><p><strong>## 13. Prompting rules that make manual sessions reliable</strong></p><p>Use prompts that name concrete files, stages, and stopping points.</p><p>Good prompts:</p><p>- “Load context before acting.”</p><p>- “Work only on US-2.”</p><p>- “Create the artifact and run the gate.”</p><p>- “Do not write code until I approve the plan.”</p><p>- “Run the exact command from the sprint contract.”</p><p>- “Record evidence before changing status.”</p><p>- “Stop and report the blocker if the emulator or platform service is unavailable.”</p><p>Avoid prompts such as:</p><p>- “Build the whole feature.”</p><p>- “Fix everything.”</p><p>- “Make the UI match.”</p><p>- “Run whatever tests seem useful.”</p><p>- “Mark it done if it mostly works.”</p><p>The more a prompt leaves to interpretation, the more likely the agent is to skip a gate or broaden the scope.</p><p><strong>## 14. The compact daily prompt</strong></p><p>After the workspace and approvals already exist, the session-resume prompt is still:</p><pre>Load context</pre><p>The context-management skill loads the current project state and next backlog task. If you need to override the selected task, add one short follow-up:</p><pre>Work on docs/product/&lt;feature-workspace&gt;/, slice US-2, using<br>harness-generator workflow.</pre><p><strong>## 15. Closing checklist</strong></p><p>Before sending a manual prompt, confirm:</p><p>- The session starts with Load context.</p><p>- The task type or workflow override is clear.</p><p>- The target workspace or slice is named.</p><p>- The expected artifact is named.</p><p>- The verification command is named.</p><p>- The approval or stopping point is explicit.</p><p>- The agent is told what it must not do.</p><p>That is the practical way to use the harness: prompt the workflow, not just the feature. The workflow tells the agent what context to load, what artifact to create, what evidence to collect, and when it must stop and wait for a human decision.</p><p>For your further reading, the Loop Engineering idea is covered in my earlier article: <a href="https://weidianhuang.medium.com/how-to-build-a-high-quality-mobile-app-in-seven-days-with-loop-engineering-d4f0da10bd1b">How to Build a High-Quality Mobile App in Seven Days with Loop Engineering</a>.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=b7154d9e3471" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[How to Build a High-Quality Mobile App in Seven Days with Loop Engineering]]></title>
            <link>https://weidianhuang.medium.com/how-to-build-a-high-quality-mobile-app-in-seven-days-with-loop-engineering-d4f0da10bd1b?source=rss-865711e189d8------2</link>
            <guid isPermaLink="false">https://medium.com/p/d4f0da10bd1b</guid>
            <category><![CDATA[ai]]></category>
            <category><![CDATA[ai-agent]]></category>
            <category><![CDATA[harness-engineering]]></category>
            <category><![CDATA[android]]></category>
            <category><![CDATA[loop-engineering]]></category>
            <dc:creator><![CDATA[Weidian Huang]]></dc:creator>
            <pubDate>Sat, 15 Aug 2026 00:11:54 GMT</pubDate>
            <atom:updated>2026-08-15T00:19:42.784Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*aoJ2YA_eqIUvIre2rD6P1g.png" /></figure><p><em>A practical Android workflow using Kotlin, Jetpack Compose, Pen.dev, MCP, AI coding CLIs, and a structured development harness.</em></p><p>Can a high-quality mobile app be built in seven days?</p><p>The answer depends on what “high quality” means.</p><p>It does not mean building a huge application with unlimited features in one week. It means building a focused MVP or product increment with:</p><ul><li>Clear product requirements</li><li>Consistent UI design</li><li>Clean architecture</li><li>Automated tests</li><li>Runtime verification</li><li>Human review</li><li>Documented decisions</li><li>A repeatable delivery process</li></ul><p>In my current Android project, NotesTakingApp, I use a development method called Loop Engineering.</p><p>The project uses Kotlin, Jetpack Compose, Material 3, Room, Hilt, KSP, and Java 17. The application includes note editing, folders, AI summarization, sharing, export, security, and voice-note capabilities.</p><p>The goal of Loop Engineering is not simply to generate code faster. It is to make every development loop small, testable, reviewable, and repeatable.</p><h3>What is Loop Engineering?</h3><p>Loop Engineering treats software development as a continuous feedback loop:</p><pre>Context → Specify → Design → Generate → Implement → Test → Review → Record → Repeat</pre><p>Each loop produces a verified result.</p><p>Instead of asking an AI agent to “build the entire app,” I give it:</p><ul><li>The project context</li><li>A specific feature</li><li>The design system</li><li>Acceptance criteria</li><li>Verification commands</li><li>The correct project workflow</li><li>The skills required for the current stage</li></ul><p>The agent implements one bounded feature or slice, runs the required checks, records the evidence, and then the next loop begins.</p><p>The project does not depend on conversation memory. It depends on specifications, design files, tests, feature trackers, and review reports.</p><h3>What makes the app high quality?</h3><p>A fast app is not automatically a high-quality app.</p><p>In this workflow, quality means that each feature is:</p><ul><li>Correctly scoped</li><li>Consistent with the product vision</li><li>Implemented within the architecture</li><li>Covered by appropriate tests</li><li>Visually verified</li><li>Reviewed by a human</li><li>Safe to continue developing</li></ul><p>For the Android project, the architecture follows:</p><pre>UI → Presentation → Domain ← Data</pre><p>Compose screens render state. ViewModels coordinate use cases. Domain code owns business rules. Data code owns Room, APIs, DTOs, and mappings.</p><p>The project also requires:</p><ul><li>No business logic inside Composables</li><li>No DTOs outside the data layer</li><li>Localized strings</li><li>Stable testTag values</li><li>Unit and integration tests</li><li>Instrumented tests for important runtime flows</li><li>Static analysis and formatting checks</li><li>Visual verification for UI changes</li></ul><p>These constraints are what prevent AI-generated code from becoming a fragile prototype.</p><h3>Day 1: Set up the harness and define the product</h3><p>The first day is about reducing ambiguity before implementation begins.</p><h3>Load the project context</h3><p>The session begins with the project instructions and core rules:</p><ul><li>AGENTS.md</li><li>Android architecture rules</li><li>Testing strategy</li></ul><p>The context is loaded in layers:</p><ul><li>L1: rules that apply to every session</li><li>L2: skills required for the current workflow</li><li>L3: feature-specific source files and knowledge documents</li></ul><p>This avoids loading the entire repository without a clear purpose.</p><p>The project also defines different workflows for different types of work:</p><ul><li>harness-planning for complex features</li><li>harness-generator for implementation</li><li>harness-evaluation for review</li><li>harness-fix for evaluator findings</li><li>feature-delivery for smaller enhancements</li><li>bug-fixing for defects and regressions</li><li>create-ui-and-verify for focused UI work</li></ul><h3>Research and build the product inventory</h3><p>Next, I create the product inventory.</p><p>The inventory describes:</p><ul><li>Product vision</li><li>Existing capabilities</li><li>Main user journeys</li><li>Planned features</li><li>Technical architecture</li><li>Feature priorities</li><li>Active feature lifecycle</li></ul><p>For NotesTakingApp, the inventory includes note creation, folders, AI summarization, sharing, export, security, and navigation.</p><p>It also records planned product areas such as Voice Notes &amp; Audio Transcripts, full-text search, attachments, and cloud synchronization.</p><p>The inventory prevents the AI agent from generating disconnected screens. It provides product-level context before feature work begins.</p><h3>Design the main pages with Pen.dev</h3><p>I use Pen.dev/Pencil.dev to design the main application pages and establish the product’s visual language.</p><p>At this stage, I focus on:</p><ul><li>Colors</li><li>Typography</li><li>Spacing</li><li>Component shapes</li><li>Navigation</li><li>Cards</li><li>Bottom sheets</li><li>Empty states</li><li>Loading states</li><li>Error states</li><li>Accessibility patterns</li></ul><p>The project stores the design source in UX/NotesApp.pen.</p><p>The design decisions are then codified into docs/product/design_system.md. This can also be generated by Pen.dev.</p><p>In NotesTakingApp, the design system defines a Light Theme baseline with:</p><ul><li>#F8F7FF screen backgrounds</li><li>#FFFFFF surfaces</li><li>#7C6CF2 as the primary accent</li><li>A 4dp, 8dp, 12dp, 16dp, 24dp, and 32dp spacing scale</li><li>Minimum 48dp interactive targets</li><li>Stable testTag values</li><li>Accessibility and responsive-layout requirements</li></ul><p>The design system becomes the shared contract between design, mockups, implementation, and UI verification.</p><h3>Day 2: Generate the initial UI with MCP</h3><p>On Day 2, the design context can be connected to the coding workflow through an MCP server.</p><p>The MCP handoff is useful for generating the initial application shell and main pages:</p><ul><li>Theme setup</li><li>Navigation structure</li><li>Screen layouts</li><li>Reusable components</li><li>Basic interaction states</li></ul><p>The generated code is treated as a starting point, not finished production code.</p><p>The first feedback loop is:</p><pre>Generate → Compile → Install → Inspect → Correct</pre><p>The generated UI must still follow the project architecture:</p><pre>UI → Presentation → Domain ← Data</pre><p>The goal of Day 2 is to establish a functioning visual foundation, not to generate every future feature.</p><h3>Why I do not use Pen.dev for every feature</h3><p>My original plan was:</p><pre>Pen.dev design<br>    ↓<br>MCP server<br>    ↓<br>Generated Compose code</pre><p>This can work well for the initial application shell.</p><p>However, repeating the full design-to-code handoff for every feature can be troublesome. Design components do not always map cleanly to Compose components. Small visual changes may require another round-trip through the design tool and MCP server.</p><p>That is why I use Pen.dev mainly to establish the visual foundation.</p><p>For new features, I use Codex with the project’s ux-design skill.</p><p>The workflow becomes:</p><pre>Pen.dev<br>    ↓<br>design_system.md<br>    ↓<br>Feature specification<br>    ↓<br>ux-design skill<br>    ↓<br>Codex-generated mockup<br>    ↓<br>Compose implementation</pre><p>The ux-design skill reads the design system and generates:</p><ul><li>A feature-level design.md</li><li>UI mockups</li><li>Component inventories</li><li>Required UI states</li><li>Stable test tags</li><li>Design prompts using the project’s semantic tokens</li></ul><p>This is faster for ordinary screens because Codex can generate the mockup directly during planning while still following the established visual system.</p><p>It works well for:</p><ul><li>Settings screens</li><li>Forms</li><li>Lists</li><li>Empty states</li><li>Simple dashboards</li><li>Basic modal sheets</li></ul><p>For highly complex visual work, custom illustrations, or pixel-perfect marketing screens, I would still return to Pen.dev or another dedicated design tool.</p><p>The principle is:</p><blockquote><em>Use Pen.dev to define the visual language. Use Codex to extend that language efficiently.</em></blockquote><h3>Days 3–6: Plan several large features every day</h3><p>From Day 3 through Day 6, planning and implementation happen continuously.</p><p>At the beginning of each day, I use the harness-planning workflow to prepare two or three substantial features.</p><p>The planning workflow uses:</p><ul><li>feature-specification</li><li>slice-planning</li><li>ux-design when UI is affected</li></ul><p>Each planned feature receives:</p><ul><li>spec.md</li><li>design.md when needed</li><li>Feature mockups</li><li>feature_list.json</li><li>sprint-contract.md</li><li>Acceptance tests</li><li>Verification commands</li><li>A defined implementation order</li></ul><p>These are not vague feature ideas. Each one is a complete work package with clear user behavior and measurable acceptance criteria.</p><p>For example, a day might produce:</p><pre>Feature 1: Voice recording<br>Feature 2: Note search<br>Feature 3: Folder organization</pre><p>For the Voice Notes feature, the planning workflow breaks the larger idea into vertical slices:</p><ol><li>Prove and persist a safe recording session.</li><li>Show progressive transcription with safe fallback.</li><li>Start recording from Home or the editor.</li><li>Save and edit inline VoiceNote blocks.</li><li>Configure Voice Notes and verify the completed Light Theme flow.</li></ol><p>The planning process can prepare multiple features, but implementation remains controlled. The project processes one active feature at a time.</p><h3>Why I keep human approval in the planning loop</h3><p>Technically, the planning process can be fully automated.</p><p>An AI agent can read the product requirements, answer its own open questions, create the specification, generate feature slices, and continue without waiting for the user.</p><p>However, the result may be technically reasonable but product-wise wrong.</p><p>Open questions often involve decisions such as:</p><ul><li>Which behavior should be the default?</li><li>Which edge cases matter most?</li><li>What should be postponed?</li><li>Which user journey is more important?</li><li>Should a feature be simple or highly configurable?</li><li>Does the proposed workflow match the product vision?</li></ul><p>The AI can choose a plausible answer, but it cannot always know what I want the product to become.</p><p>The same applies to UI mockups. The ux-design skill can generate a design that follows design_system.md, uses the correct colors and spacing, and satisfies the component rules. But I still need to review:</p><ul><li>Visual hierarchy</li><li>Information density</li><li>User flow</li><li>Wording</li><li>Interaction priority</li><li>Brand feeling</li><li>Whether the screen solves the real user problem</li></ul><p>For that reason, I keep human approval at two important points:</p><pre>AI identifies open questions<br>        ↓<br>Human answers the product questions<br>        ↓<br>AI writes the specification and design<br>        ↓<br>Human reviews the mockups<br>        ↓<br>AI creates the feature slices and sprint contract<br>        ↓<br>Human approves the implementation queue</pre><p>This is not a rejection of automation. It is a way to automate execution without automating product intent.</p><h3>The implementation queue</h3><p>After the specifications and sprint contracts are approved, the features enter the project tracker.</p><p>A cron-style scheduler then invokes auto-harness-generator.sh.</p><p>On macOS, this project uses launchd rather than traditional cron. Codex CLI and Antigravity CLI are two supported command-line agents, but the loop is not tied to one specific tool. Any compatible AI CLI can perform the same role if it accepts the generated workflow prompt and can work inside the repository.</p><p>The scheduler selects one approved feature at a time and runs it through the harness-generator workflow.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*JbN3dN9d9v9YqcPr9Su2nw.png" /></figure><h3>The complete big-feature lifecycle</h3><p>A large feature is not complete when the generator finishes writing code.</p><p>After all of its slices pass, the feature goes through automated evaluation and human review.</p><p>The complete lifecycle is:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*v7tf2mpUH_qk0-vy7W0qRw.png" /></figure><p>There are two different kinds of review findings.</p><h3>Findings from automated evaluation</h3><p>harness-evaluation checks the completed feature against:</p><ul><li>The specification</li><li>Sprint contract</li><li>Acceptance tests</li><li>Architecture rules</li><li>Testing strategy</li><li>Design system</li><li>Code quality</li><li>Evidence requirements</li></ul><p>If the evaluator finds issues, the feature moves to harness-fix.</p><p>The harness-fix workflow resolves every code-review and test-review finding before the feature proceeds to human review.</p><h3>Bugs found during human review</h3><p>After automated evaluation, I manually test the feature in the real application.</p><p>Human testing checks:</p><ul><li>Real production entry points</li><li>User flows</li><li>UI behavior</li><li>Copy and visual hierarchy</li><li>Edge cases</li><li>State restoration</li><li>Device behavior</li><li>Regressions in existing features</li></ul><p>If a bug is discovered, I use the ad-hoc bug-fixing workflow.</p><p>That workflow reproduces the issue, adds a failing regression test, fixes the root cause, and reruns the relevant checks.</p><pre>Human review finds a bug<br>        ↓<br>bug-fixing workflow<br>        ↓<br>Reproduce the bug<br>        ↓<br>Write a failing regression test<br>        ↓<br>Fix the implementation<br>        ↓<br>Run regression and quality checks<br>        ↓<br>Human re-review</pre><p>This distinction is important:</p><ul><li>harness-fix resolves findings from formal code and test evaluation.</li><li>bug-fixing resolves defects discovered during human testing.</li></ul><h3>Day 7: Implement small features and fix remaining bugs</h3><p>Day 7 is reserved for smaller enhancements, remaining bugs, and final polish.</p><p>For small enhancements, I use the ad-hoc feature-delivery workflow.</p><p>This is appropriate for work such as:</p><ul><li>A small settings option</li><li>A minor UI improvement</li><li>A simple navigation adjustment</li><li>A missing empty state</li><li>A small accessibility enhancement</li><li>A localized copy change</li></ul><p>The feature-delivery workflow still requires a clear requirement, implementation plan, tests, and quality checks. Small does not mean unverified.</p><p>For bugs discovered during the final review, I continue using the ad-hoc bug-fixing workflow.</p><p>The final day looks like this:</p><pre>Remaining small feature<br>        ↓<br>feature-delivery workflow<br>        ↓<br>Implementation plan approval<br>        ↓<br>Implementation and tests<br>        ↓<br>Quality checks</pre><pre>Remaining bug<br>        ↓<br>bug-fixing workflow<br>        ↓<br>Reproduction test<br>        ↓<br>Root-cause fix<br>        ↓<br>Regression testing</pre><p>The final verification includes:</p><pre>./gradlew assembleDebug<br>./gradlew testDebugUnitTest<br>./gradlew ktlintCheck<br>./gradlew detekt<br>./gradlew connectedDebugAndroidTest<br>./gradlew installDebug</pre><p>For UI changes, I also compare the running application against the approved mockups and design_system.md.</p><h3>Why this approach produces higher quality</h3><p>The project has a clear location for every important decision:</p><ul><li>Product scope lives in the product inventory.</li><li>Visual decisions live in the design system.</li><li>Requirements live in the specification.</li><li>Feature order lives in the feature list.</li><li>Acceptance tests live in the sprint contract.</li><li>Implementation progress lives in summaries and logs.</li><li>Historical decisions live in ADRs and knowledge documents.</li><li>Completion is proven through tests and runtime evidence.</li></ul><p>The AI agent does not need to rediscover the project from scratch during every session.</p><p>It reads the current state, implements one slice, verifies the result, records the evidence, and continues with the next queued feature.</p><p>The human remains responsible for product intent and final usability. The AI handles structured execution, code generation, test generation, and repetitive verification.</p><h3>What can realistically be built in seven days?</h3><p>Seven days is realistic for:</p><ul><li>A focused MVP</li><li>An internal productivity tool</li><li>A narrow consumer application</li><li>A new vertical feature</li><li>A prototype with production-quality foundations</li></ul><p>It is not automatically enough for:</p><ul><li>A large social network</li><li>A regulated financial product</li><li>A complex marketplace</li><li>A multi-region backend platform</li><li>An application with extensive third-party integrations</li></ul><p>The seven-day limit is mainly a scope constraint.</p><p>The app becomes possible because the work is divided into vertical slices, design decisions are reusable, planning is continuous, and each loop produces evidence.</p><h3>Final takeaway</h3><p>Building a high-quality mobile app in seven days is not about generating more code.</p><p>It is about creating a system where every iteration is:</p><ul><li>Small enough to finish</li><li>Clear enough to verify</li><li>Designed enough to remain consistent</li><li>Documented enough to continue</li><li>Tested enough to trust</li><li>Reviewed enough to improve</li><li>Safe enough to automate</li></ul><p>The complete process looks like this:</p><pre>Product inventory<br>→ Design system<br>→ Daily feature planning<br>→ Human answers product questions<br>→ Approved feature queue<br>→ Generated mockup<br>→ Implementation<br>→ Automated tests<br>→ Evaluation<br>→ Fix evaluator findings<br>→ Human review and testing<br>→ Fix human-discovered bugs<br>→ Small-feature delivery<br>→ Final verification</pre><p>That is Loop Engineering: a development process that keeps moving quickly without losing product intent, architectural discipline, visual quality, or user trust.</p><h3>Explore the Loop Engineering</h3><p>The full implementation — all scripts, workflows, stages, rules and skills— is available in the open-source NotesTakingApp project on GitHub: <a href="https://github.com/hwdavr/NotesTakingApp"><strong>NotesTakingApp</strong></a></p><h3>Continue reading</h3><p>This seven-day workflow is a practical application of the broader harness-engineering ideas behind the project.</p><p>If you want to understand how workflows, rules, skills, feature trackers, automated agents, and quality gates can turn AI coding agents into a reliable engineering team, read my related series:</p><p><a href="https://medium.com/@weidianhuang/harness-engineering-how-to-turn-ai-coding-agents-into-a-reliable-engineering-team-16af4f27775c">Harness Engineering: How to Turn AI Coding Agents into a Reliable Engineering Team</a></p><p>Loop Engineering focuses on delivering the app quickly. Harness Engineering explains the system that makes that speed reliable.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=d4f0da10bd1b" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Harness Engineering: Harnesses Raise the Floor and Lower the Blast Radius]]></title>
            <link>https://weidianhuang.medium.com/the-harness-matters-more-than-the-model-you-pick-ba5f8d66c238?source=rss-865711e189d8------2</link>
            <guid isPermaLink="false">https://medium.com/p/ba5f8d66c238</guid>
            <category><![CDATA[harness]]></category>
            <category><![CDATA[ai-coding]]></category>
            <category><![CDATA[android]]></category>
            <category><![CDATA[harness-engineering]]></category>
            <category><![CDATA[ai]]></category>
            <dc:creator><![CDATA[Weidian Huang]]></dc:creator>
            <pubDate>Tue, 11 Aug 2026 23:43:40 GMT</pubDate>
            <atom:updated>2026-08-31T13:02:37.402Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*KbSGJ94WXTzFcQusNIAc3w.png" /></figure><p>This article is part of my <strong>AI Coding Harness Engineering</strong> series, where I explore how to make AI coding agents more reliable for real software engineering work.</p><p>Rather than focusing only on model capability or prompt engineering, this series looks at the agentic system around the model: specifications, task decomposition, persistent context, verification gates, UI feedback, evaluator loops, and long-running workflows.</p><p><strong>Part 1 — </strong><a href="https://medium.com/@weidianhuang/harness-engineering-how-to-turn-ai-coding-agents-into-a-reliable-engineering-team-16af4f27775c"><strong>Why AI Coding Agents Need a Harness</strong></a><br>Why coding agents need an engineering harness around them, and the core failure modes the harness is designed to control.</p><p><strong>Part 2 — </strong><a href="https://medium.com/@weidianhuang/harness-engineering-how-to-set-up-an-android-agent-harness-b7154d9e3471"><strong>How to Set Up an Android Agent Harness</strong></a><br>A practical guide on using the Android agent harness in your project.</p><p><strong>Part 3 — </strong><a href="https://medium.com/@weidianhuang/harness-engineering-building-a-test-harness-that-can-prove-software-works-9c15ca65e8e5"><strong>Building a Test Harness That Can Prove Software Works</strong></a><strong><br></strong>A practical guide to tracing software requirements through tests, evidence, and review using an Android harness.</p><p><strong>Part 4 — </strong><a href="https://medium.com/@weidianhuang/harness-engineering-why-ui-design-should-start-inside-harness-planning-ffe27b89412b"><strong>Why UI Design Should Start Inside Harness Planning</strong></a><br>UX improves when design generation, harness planning, and runtime verification work together in one continuous loop.</p><p><strong>Part 5 — </strong><a href="https://medium.com/@weidianhuang/harness-engineering-building-coding-rules-into-an-ai-harness-1b259f69317a"><strong>Building Coding Rules Into an AI Harness</strong></a><strong><br></strong>Discover how an AI coding harness turns fragile rule-following into reliable quality by combining context-aware requirements, deterministic scripts, and independent evaluation.</p><p><strong>Part 6 — </strong><a href="https://medium.com/@weidianhuang/the-harness-matters-more-than-the-model-you-pick-ba5f8d66c238"><strong>Harnesses Raise the Floor and Lower the Blast Radius</strong></a><br>How engineering constraints affect smaller and larger models differently, and why stronger models still benefit from a well-designed harness.</p><p><strong>Part 7 — </strong><a href="https://medium.com/@weidianhuang/harness-engineering-building-a-retrospective-feedback-loop-b535915d0200"><strong>Building a Retrospective Feedback Loop</strong></a><strong><br></strong>How to build a continuous-improvement harness system around your project.</p><p>Source repositories:</p><ul><li><a href="https://github.com/hwdavr/NotesTakingApp/tree/master">NotesTakingApp</a></li><li><a href="https://github.com/hwdavr/android-agent-harness">android-agent-harness</a></li></ul><p>Most coding-agent discussions still start with the same question:</p><p>Which model is strongest?</p><p>After building a harness around an Android project, I’ve found a more useful question:</p><p>What’s the smallest model that can reliably complete this task inside a good engineering system?</p><p>That change in perspective matters.</p><p>A larger model still has a higher capability ceiling. But if your requirements are clear, the task is broken down far enough, and verification is strong enough, a smaller model can handle much more work than you might expect.</p><p>That’s why GPT-5.6 Luna with Max reasoning can do most of the implementation work in my harness project.</p><p>Not because Luna becomes Sol.</p><p>Because the harness changes the problem the model has to solve.</p><h3>The harness reduces how much the model has to figure out</h3><p>Imagine giving an agent this instruction:</p><blockquote><em>Build the new editor feature.</em></blockquote><p>The model now has to make dozens of decisions.</p><p>Which files should it change? Which architecture should it follow? Should it refactor existing code? Which tests are needed? How does it know the UI is correct? When is the feature actually finished?</p><p>A stronger model has an obvious advantage when the task contains that much uncertainty.</p><p>But I don’t want the model making all of those decisions.</p><p>I want the engineering system to make as many of them explicit as possible.</p><p>In my harness, the workflow looks closer to:</p><p>Requirement → plan → small vertical slice → implementation → build → tests → lint → UI verification → evaluation → correction</p><p>The model still writes and reasons about code. But it no longer has to invent the development process while doing so.</p><h3>Think of the harness as a control zone</h3><p>This diagram captures the idea.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*lqVaBHrputyowUztpnykOA.png" /></figure><p>The horizontal axis represents time as the model works through a long-running task.</p><p>The vertical axis represents the scope of change: roughly how many files, modules, or parts of the system it touches.</p><p>Without a strong harness, smaller and larger models can fail in opposite directions.</p><p>A smaller model tends to fall toward the bottom-left. It makes the obvious changes, misses part of the requirement, and decides it’s finished too early.</p><p>A much stronger model can move in the other direction. It understands more of the repository, sees more opportunities for improvement, and starts touching code outside the intended scope.</p><p>The harness tries to keep both behaviors inside a useful operating range.</p><p>I describe it this way:</p><blockquote><em>The harness raises the floor for smaller models and lowers the blast radius of larger models.</em></blockquote><h3>Raise the floor for smaller models</h3><p>A smaller model becomes much more useful when you remove uncertainty around it.</p><p>First, make the requirements explicit.</p><p>Then make the task smaller.</p><p>Instead of asking:</p><blockquote><em>Build the collage editor.</em></blockquote><p>ask for one bounded vertical slice:</p><blockquote><em>Add the canvas state model using the existing editor pattern. Modify only these modules. Add the required tests. Run the verification commands and fix failures before finishing.</em></blockquote><p>That’s a very different problem.</p><p>Then add feedback.</p><p>Builds tell the model whether the code compiles.</p><p>Tests tell it whether behavior is correct.</p><p>Lint and static checks catch structural mistakes.</p><p>UI verification tells it whether the screen actually looks and behaves as expected.</p><p>Evaluators can identify incomplete work and send the model back for another attempt.</p><p>Now the model doesn’t have to get everything right in one pass.</p><p>That’s especially important for smaller models.</p><h3>Smaller slices need less raw model capability</h3><p>This is the core idea behind my approach.</p><p>As requirement clarity increases, task size decreases, and verification becomes stronger, the amount of model capability needed to complete the work reliably also decreases.</p><p>The harness doesn’t make Luna more intelligent.</p><p>It makes the problem easier to solve correctly.</p><p>A lot of software work can be transformed this way.</p><p>A large feature might look difficult when treated as one open-ended problem. But break it into ten well-specified slices, give the model established patterns, verify each result, and allow correction between slices.</p><p>Suddenly the task looks very different.</p><p>In my project, Luna can handle work such as:</p><ul><li>Compose screens that follow an existing design pattern</li><li>ViewModels and state handling</li><li>domain use cases</li><li>repository and mapper implementation</li><li>unit and integration tests</li><li>compilation and lint fixes</li><li>documentation updates</li><li>UI verification</li><li>evaluator findings and corrections</li></ul><p>These aren’t necessarily trivial tasks.</p><p>They’re constrained tasks.</p><p>That distinction is more important.</p><h3>I also use smaller models to test the harness itself</h3><p>This became one of the most useful lessons from building the system.</p><p>I don’t only use a smaller model because it’s cheaper.</p><p>I use it as a test of the harness.</p><p>If Luna repeatedly fails on a task that I believe should be straightforward, I don’t immediately conclude that Luna isn’t capable enough.</p><p>I first ask:</p><p>Why did the harness allow this failure?</p><p>Maybe the specification is ambiguous.</p><p>Maybe the vertical slice is still too large.</p><p>Maybe the repository pattern isn’t easy to discover.</p><p>Maybe an architecture rule exists only in my head.</p><p>Maybe the evaluator can detect a failure but doesn’t explain how to recover from it.</p><p>Maybe UI verification is missing an important state.</p><p>Maybe the definition of “done” isn’t actually enforceable.</p><p>A stronger model can sometimes hide these weaknesses because it fills in the missing information itself.</p><p>That can make your harness look better than it really is.</p><p>A smaller model exposes the gaps.</p><p>I’ve found this surprisingly valuable.</p><p>When Luna struggles with a supposedly well-defined task, that failure becomes feedback about my software system.</p><p>I can improve the specification, decomposition, skills, verification, or recovery loop and run the task again.</p><p>If Luna can eventually complete it reliably, the harness has improved.</p><p>And that improvement benefits every model, including Sol.</p><p>So the smaller model isn’t just an execution engine.</p><p>It’s also a stress test for the quality of the harness.</p><h3>Strong models need control too</h3><p>The opposite problem appears with highly capable models.</p><p>Suppose you ask for a small UI change.</p><p>A strong model may notice that the navigation abstraction could be improved. It may discover inconsistent naming. It may decide to generalize a shared component or refactor an adjacent module.</p><p>Those observations might be correct.</p><p>But they aren’t necessarily part of the task.</p><p>That’s why the upper boundary in the diagram matters.</p><p>The harness needs mechanical controls such as:</p><ul><li>explicit file boundaries</li><li>architecture constraints</li><li>diff validation</li><li>tests</li><li>static checks</li><li>permissions</li><li>review gates</li><li>evidence requirements</li></ul><p>An instruction saying “don’t modify unrelated code” is useful.</p><p>It isn’t enforcement.</p><p>If a task should touch six files and the model changes seventeen, the harness should detect that.</p><p>If the model claims completion, it should provide evidence.</p><p>Build passed.</p><p>Tests passed.</p><p>Lint passed.</p><p>UI verified.</p><p>Diff is within scope.</p><p>The purpose isn’t to reduce the model’s intelligence.</p><p>It’s to keep that intelligence focused on the job you actually asked it to do.</p><h3>How far apart are Sol, Terra, Luna and GPT-5.5?</h3><p>OpenAI’s published coding benchmarks show a clear capability order overall, but the gap is more nuanced than “new small model = weaker than previous-generation large model.”</p><iframe src="https://cdn.embedly.com/widgets/media.html?src=https%3A%2F%2Fdatawrapper.dwcdn.net%2FKVfbf%2F1%2F&amp;display_name=Datawrapper&amp;url=https%3A%2F%2Fdatawrapper.dwcdn.net%2FKVfbf%2F1%2F&amp;image=https%3A%2F%2Fdatawrapper.dwcdn.net%2FKVfbf%2Fplain-s.png%3Fv%3D1&amp;type=text%2Fhtml&amp;schema=dwcdn" width="600" height="296" frameborder="0" scrolling="no"><a href="https://medium.com/media/1198a86c67ba427cde93f72a544af4dd/href">https://medium.com/media/1198a86c67ba427cde93f72a544af4dd/href</a></iframe><p>Sol is still the strongest model overall, and Terra generally sits between Sol and Luna.</p><p>But Luna is more interesting than the tier name suggests.</p><p>On SWE-Bench Pro, Luna scores 62.7%, compared with 59.4% for GPT-5.5. That’s a 3.3-point lead.</p><p>On DeepSWE v1.1, Luna also edges ahead: 67.2% versus 67.0%.</p><p>So Luna is not just a cheaper fallback. On some structured software-engineering benchmarks, it already matches or exceeds GPT-5.5.</p><p>That matters for a harness-driven workflow.</p><p>If you already considered GPT-5.5 capable enough for serious coding work, then Luna’s results suggest that a smaller GPT-5.6 model can still be a very credible default for constrained implementation tasks.</p><p>The key point isn’t that Luna beats GPT-5.5 everywhere. It doesn’t. GPT-5.5 still scores higher on the Coding Agent Index and Terminal-Bench 2.1.</p><p>The point is that model tier alone doesn’t tell you enough.</p><p>For the kind of work a harness is designed to create — small, explicit, verifiable engineering slices — Luna is already operating in the same performance range, and on some benchmarks it performs better.</p><p>That’s why I don’t think of Luna as “the weak model.”</p><p>I think of it as:</p><blockquote><em>A lower-cost model that is already strong enough for a large percentage of structured engineering work.</em></blockquote><p>And once the harness removes ambiguity, constrains scope, and provides strong feedback, that becomes even more useful.</p><p>A good transition into the next section would be:</p><blockquote><em>The benchmark gap is real, but the harness determines how often your task actually depends on that gap.</em></blockquote><h3>The economics make model routing even more interesting</h3><p>The current GPT-5.6 API prices are also quite different.</p><p>Sol costs $5 per million input tokens and $30 per million output tokens.</p><p>Terra costs $2.50 and $15.</p><p>Luna costs $1 and $6.</p><iframe src="https://cdn.embedly.com/widgets/media.html?src=https%3A%2F%2Fdatawrapper.dwcdn.net%2F4f3Z1%2F1%2F&amp;display_name=Datawrapper&amp;url=https%3A%2F%2Fdatawrapper.dwcdn.net%2F4f3Z1%2F1%2F&amp;image=https%3A%2F%2Fdatawrapper.dwcdn.net%2F4f3Z1%2Fplain-s.png%3Fv%3D1&amp;type=text%2Fhtml&amp;schema=dwcdn" width="600" height="191" frameborder="0" scrolling="no"><a href="https://medium.com/media/b68ef4f40a5ec7572c6e516a23602eae/href">https://medium.com/media/b68ef4f40a5ec7572c6e516a23602eae/href</a></iframe><p>Luna is therefore 80% cheaper than Sol at the standard per-token rates. OpenAI itself describes Luna as the fastest and most cost-efficient GPT-5.6 model.</p><p>That matters for long-running coding agents.</p><p>They consume tokens reading repository context, inspecting files, processing build logs, reviewing test failures, evaluating diffs, checking UI states and retrying work.</p><p>So I don’t want to ask:</p><p>How do I use the fewest tokens?</p><p>I want to ask:</p><p>Where does expensive reasoning actually change the result?</p><h3>Luna for execution, Sol for discovery</h3><p>This gives me a practical routing strategy.</p><p>If the harness already knows the path and mainly needs disciplined execution, I start with Luna.</p><p>For example:</p><blockquote><em>Implement this ViewModel using the existing pattern.</em></blockquote><p>Luna.</p><blockquote><em>Add these tests, run them and fix the failures.</em></blockquote><p>Luna.</p><blockquote><em>Implement the next UI slice and verify it on the emulator.</em></blockquote><p>Luna.</p><p>But consider:</p><blockquote><em>The specification conflicts with the current architecture. Decide which design should change.</em></blockquote><p>That’s different.</p><p>Or:</p><blockquote><em>We have an intermittent lifecycle bug across Compose, coroutines and navigation, and nobody knows the root cause.</em></blockquote><p>Or:</p><blockquote><em>Redesign this subsystem while preserving behavior across several features.</em></blockquote><p>Those are much better reasons to use Sol.</p><p>Sol is most valuable when the system still needs to discover the answer.</p><p>Luna is often enough when the harness already knows what “good” looks like.</p><h3>Don’t let a stronger model hide a weaker harness</h3><p>This is probably the biggest change in how I now evaluate my system.</p><p>If I test everything with the strongest model available, I may get impressive results while missing structural problems in the harness.</p><p>The model compensates for vague instructions.</p><p>It guesses missing context.</p><p>It recovers from weak decomposition.</p><p>It notices things my verification system failed to check.</p><p>That looks like success.</p><p>But some of that success belongs to the model, not the harness.</p><p>Run the same workflow with a smaller model and those weaknesses become obvious.</p><p>That’s useful.</p><p>I want the harness to carry as much of the process as possible:</p><p>the requirements,</p><p>the boundaries,</p><p>the memory,</p><p>the workflow,</p><p>the feedback,</p><p>the definition of done,</p><p>and the recovery path.</p><p>Then the model can concentrate on the part it’s actually good at: reasoning about and implementing the next piece of work.</p><h3>The harness narrows the capability gap</h3><p>A harness doesn’t erase the difference between models.</p><p>Sol still has the higher ceiling.</p><p>Some problems genuinely require it.</p><p>But a good harness changes how often you need to reach that ceiling.</p><p>It reduces ambiguity.</p><p>It decomposes complexity.</p><p>It externalizes context.</p><p>It provides feedback.</p><p>It makes failure recoverable.</p><p>It constrains unnecessary changes.</p><p>And, importantly, a smaller model can help you discover where those mechanisms are still weak.</p><p>That’s why I wouldn’t say:</p><blockquote><em>Luna becomes as capable as Sol inside my harness.</em></blockquote><p>I’d say:</p><blockquote><em>My harness makes many tasks constrained enough that Luna doesn’t need to be Sol.</em></blockquote><p>That distinction captures the whole idea.</p><p>Sol raises the capability ceiling.</p><p>The harness raises the floor for smaller models and lowers the blast radius of larger ones.</p><p>And using a smaller model to expose weaknesses helps me keep moving those boundaries in the right direction.</p><p>So I no longer ask only:</p><p>Which model is strongest?</p><p>I ask two questions:</p><p>What’s the smallest model that can reliably complete this task?</p><p>And if it can’t, is the problem really the model — or have I just found the next gap in my harness?</p><h3>Bonus</h3><p>Want to use GPT-5.6 Luna for free? Try Freebuff, a desktop workspace with free models.</p><p><a href="https://freebuff.com/get-started?ref=ref-501530f0-ec0b-4be0-be45-41b8144088b5&amp;referrer=hwdavr"><strong>Try Freebuff →</strong></a></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=ba5f8d66c238" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Harness Engineering: Why AI Coding Agents Need a Harness]]></title>
            <link>https://weidianhuang.medium.com/harness-engineering-how-to-turn-ai-coding-agents-into-a-reliable-engineering-team-16af4f27775c?source=rss-865711e189d8------2</link>
            <guid isPermaLink="false">https://medium.com/p/16af4f27775c</guid>
            <category><![CDATA[vibe-coding]]></category>
            <category><![CDATA[harness-engineering]]></category>
            <category><![CDATA[android]]></category>
            <category><![CDATA[ai]]></category>
            <dc:creator><![CDATA[Weidian Huang]]></dc:creator>
            <pubDate>Sat, 18 Jul 2026 01:17:34 GMT</pubDate>
            <atom:updated>2026-08-31T13:02:22.475Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*r58qthGBFPsm_tZTohta8Q.png" /></figure><p>This article is part of my <strong>AI Coding Harness Engineering</strong> series, where I explore how to make AI coding agents more reliable for real software engineering work.</p><p>Rather than focusing only on model capability or prompt engineering, this series looks at the agentic system around the model: specifications, task decomposition, persistent context, verification gates, UI feedback, evaluator loops, and long-running workflows.</p><p><strong>Part 1 — </strong><a href="https://medium.com/@weidianhuang/harness-engineering-how-to-turn-ai-coding-agents-into-a-reliable-engineering-team-16af4f27775c"><strong>Why AI Coding Agents Need a Harness</strong></a><br>Why coding agents need an engineering harness around them, and the core failure modes the harness is designed to control.</p><p><strong>Part 2 — </strong><a href="https://medium.com/@weidianhuang/harness-engineering-how-to-set-up-an-android-agent-harness-b7154d9e3471"><strong>How to Set Up an Android Agent Harness</strong></a><br>A practical guide on using the Android agent harness in your project.</p><p><strong>Part 3 — </strong><a href="https://medium.com/@weidianhuang/harness-engineering-building-a-test-harness-that-can-prove-software-works-9c15ca65e8e5"><strong>Building a Test Harness That Can Prove Software Works</strong></a><strong><br></strong>A practical guide to tracing software requirements through tests, evidence, and review using an Android harness.</p><p><strong>Part 4 — </strong><a href="https://medium.com/@weidianhuang/harness-engineering-why-ui-design-should-start-inside-harness-planning-ffe27b89412b"><strong>Why UI Design Should Start Inside Harness Planning</strong></a><br>UX improves when design generation, harness planning, and runtime verification work together in one continuous loop.</p><p><strong>Part 5 — </strong><a href="https://medium.com/@weidianhuang/harness-engineering-building-coding-rules-into-an-ai-harness-1b259f69317a"><strong>Building Coding Rules Into an AI Harness</strong></a><strong><br></strong>Discover how an AI coding harness turns fragile rule-following into reliable quality by combining context-aware requirements, deterministic scripts, and independent evaluation.</p><p><strong>Part 6 — </strong><a href="https://medium.com/@weidianhuang/the-harness-matters-more-than-the-model-you-pick-ba5f8d66c238"><strong>Harnesses Raise the Floor and Lower the Blast Radius</strong></a><br>How engineering constraints affect smaller and larger models differently, and why stronger models still benefit from a well-designed harness.</p><p><strong>Part 7 — </strong><a href="https://medium.com/@weidianhuang/harness-engineering-building-a-retrospective-feedback-loop-b535915d0200"><strong>Building a Retrospective Feedback Loop</strong></a><strong><br></strong>How to build a continuous-improvement harness system around your project.</p><p>Source repositories:</p><ul><li><a href="https://github.com/hwdavr/NotesTakingApp/tree/master">NotesTakingApp</a></li><li><a href="https://github.com/hwdavr/android-agent-harness">android-agent-harness</a></li></ul><p>Over the past year, most AI coding discussions have focused on the next stronger model.</p><p>But after building an Android project with coding agents, my biggest lesson is different: model capability determines the ceiling, but the harness determines how much of that ceiling you can actually use.</p><p>A capable agent still fails in predictable ways. It tries to do too much at once. It loses continuity across context windows. It declares victory too early. If the context window is nearly full, or the session quota is close to ending, the model can become less rigorous: it reads less, verifies less, and summarizes instead of finishing.</p><p>My solution is not to trust the agent more. My solution is to trust the harness more.</p><p>A coding run is only useful if it completes the required workflow stages and leaves behind evidence. If it does not, I can discard that run instead of accepting lower-quality code.</p><h3>What I Learned From AI Coding: The Harness Matters More Than the Prompt</h3><p>Over the past few months, I have been building a harness engineering Android project: <a href="https://github.com/hwdavr/NotesTakingApp">hwdavr/NotesTakingApp</a>.</p><p>This article is what I am going to share from that experience: how I structured the project so coding agents can work more reliably, how the harness prevents common long-running-agent failures, and why verification matters more than trusting the model’s final answer.</p><p>Over the past year, most AI coding discussions have focused on the next stronger model.</p><p>But after building an Android project with coding agents, my biggest lesson is different: model capability determines the ceiling, but the harness determines how much of that ceiling you can actually use.</p><h3>The Starting Point: Anthropic’s Harness Article</h3><p>The starting point for this thinking is Anthropic’s article, <a href="https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents">“Effective harnesses for long-running agents”</a>.</p><p>The article explains that long-running coding agents do not fail only because the model is weak. They fail because the surrounding engineering system is weak. Below are the 3 common failures from the agent.</p><h3>Issue 1: The Agent Tries To Do Too Much At Once</h3><p>The first problem is overreach.</p><p>If I give an agent a broad requirement like “build the photo editing screen,” it may try to implement the whole thing in one pass: navigation, UI, ViewModel state, image import, editor tools, tests, and persistence. That is too much surface area for one agent session.</p><p>My project solves this with a harness-planning workflow.</p><p>The rule is simple: if the requirement is vague, the agent must not start coding. It must ask clarification questions until all open questions are answered.</p><p>After that, it generates:</p><ul><li>docs/current/spec.md</li><li>docs/current/design.md, when UI or frontend behavior is involved</li></ul><p>The spec.md defines what the system should do. But for frontend work, a spec alone is not enough. You cannot fully imagine what the UI should look like from requirements text. A design.md file is needed to describe layout, screen states, user actions, visual expectations, and what “matching the design” actually means.</p><p>This matters especially for Android Compose. A feature can be technically correct and still feel wrong: spacing is off, hierarchy is unclear, a bottom sheet opens in the wrong state, or the wrong action is emphasized. The design.md gives the agent a visual contract, not just a functional contract.</p><p>Once the spec and design are approved, the harness breaks the work into vertical slices. Each slice should be small enough to implement, test, and verify independently.</p><p>The agent no longer has to “build everything.” It has to complete the next slice.</p><h3>Issue 2: The Agent Loses Continuity Across Context Windows</h3><p>The second problem is continuity.</p><p>A long-running project cannot depend on one agent session remembering everything. Context windows reset. Sessions expire. Another agent may take over. If the previous session did not record what happened, the next one wastes time rediscovering the project state.</p><p>My rule is: every stage must produce evidence.</p><p>The repository becomes the source of truth, not the chat history.</p><p>These are the main continuity files I use:</p><ul><li>docs/current/spec.md or docs/current/spec_v&lt;N&gt;.md<br>The current requirement contract. It records what the feature must do and removes ambiguity.</li><li>docs/current/design.md and docs/current/design/<br>The UI contract. It stores visual expectations and source screenshots or mockups.</li><li>docs/current/feature_list.json<br>The machine-readable list of vertical slices. It tracks which feature is not_started, in_progress, passing, or blocked.</li><li>docs/current/sprint-contract.md<br>The agreement for the current sprint: scope, acceptance criteria, verification standards, and exclusions.</li><li>docs/current/progress.md<br>The running progress log. It helps the next session understand what changed and what remains.</li><li>docs/current/summary_{feature_id}.md <br>The stage-by-stage evidence file. Each completed stage must reference the artifact or verification result that proves it is complete.</li><li>docs/current/session-handoff.md<br>The final handoff. It records what is working, what changed, what is broken or unverified, the next best step, and the commands the next agent should run.</li><li>docs/templates/clean-state-checklist-template.md<br>The exit checklist. It prevents the agent from leaving the repo in a half-clean state.</li></ul><p>This is the key design: the next agent should not need oral history. It should be able to read the repo artifacts and continue.</p><p>That matches the lesson from the harness engineering lectures: initialization and handoff must be explicit phases, because “figuring out what happened last time” can consume a huge part of the next session.</p><h3>Issue 3: The Agent Declares Victory Too Early</h3><p>The third problem is premature completion.</p><p>Agents are very good at saying “done.” They are not always good at proving it.</p><p>In my harness, the first evidence I check is the summary file:</p><ul><li>docs/current/summary_v&lt;N&gt;.md</li><li>docs/current/summary_{feature_id}.md</li></ul><p>Each workflow stage must be marked complete in that summary file. If any stage is not ticked, the agent has declared victory too early.</p><p>That usually means it skipped part of the process: maybe it implemented code but did not run tests, or ran tests but skipped lint, or updated source files without recording evidence. The summary file becomes a simple audit trail. It tells me whether the agent actually followed the workflow or only claimed it did.</p><p>Coding rules help, but they are not enough. A rule says what should happen. Verification proves whether it happened.</p><p>In my Android project, completion requires mechanical checks such as:</p><pre>./gradlew assembleDebug<br>./gradlew testDebugUnitTest<br>./gradlew koverLog<br>./gradlew ktlintCheck<br>./gradlew detekt<br>./gradlew lintDebug<br>./gradlew connectedDebugAndroidTest</pre><p>I also use custom harness checks:</p><pre>bash scripts/check-stage-artifacts.sh &lt;workflow&gt; &lt;stage&gt;<br>bash scripts/check-compose-rules.sh<br>bash scripts/check-localization-rules.sh<br>bash scripts/check-architecture-rules.sh<br>git diff --check</pre><p>The agent cannot mark a feature as passing just because it feels done. It must update the summary file, tick every required stage, and attach evidence from successful verification commands.</p><p>If the summary file has missing stage ticks, the run is incomplete. In that case, I treat the agent’s “done” message as unreliable and send it back to the skipped stage.</p><h3>The Practical Guide: Learn Harness Engineering</h3><p>Another useful reference is the Learn Harness Engineering course: <a href="https://walkinglabs.github.io/learn-harness-engineering/en/">Learn Harness Engineering</a>.</p><p>The course helped me turn the harness idea into a concrete project structure. Anthropic’s article explains why long-running agents need a harness. The course explains what tends to break when you actually build one.</p><p>Three lessons from the course changed how I structured my Android project:</p><h3>Lesson 1: One Giant Instruction File Fails</h3><p>One of the most useful harness lessons is that a giant instruction file eventually hurts the agent.</p><p>The lecture “Why One Giant Instruction File Fails” explains the trap clearly: every time the agent makes a mistake, you add another rule to AGENTS.md. The file grows from 100 lines to 300, then 600. Eventually, the agent spends too much context reading irrelevant instructions, misses critical rules buried in the middle, and starts seeing contradictory guidance.</p><p>My solution is to break instructions by responsibility.</p><p>AGENTS.md should be the router. It contains the project overview, workflow routing, global non-negotiable rules, and core commands.</p><p>Workflows define stage order. For example, harness-planning says when to clarify, when to generate artifacts, and when to stop for approval.</p><p>Skills define how to execute one stage. For example, android-implementation explains how to implement across data, domain, presentation, and UI layers.</p><p>Rules define constraints. For example:</p><ul><li>.agents/rules/android-architecture.md</li><li>.agents/rules/testing-strategy.md</li><li>.agents/rules/compose-rules.md</li><li>.agents/rules/localization-rules.md</li><li>.agents/rules/navigation-rules.md</li><li>.agents/rules/api-contract-rules.md</li><li>.agents/rules/observability.md</li></ul><p>Scripts enforce the rules mechanically.</p><p>The mental model is:</p><ul><li>AGENTS.md: where should the agent go?</li><li>Workflow: what order should it follow?</li><li>Skill: how should this stage be performed?</li><li>Rule: what must never be violated?</li><li>Script: how do we prove it?</li></ul><p>That split improves signal-to-noise ratio and keeps context focused.</p><h3>Lesson 2: Every Session Needs Initialization And Clean Exit</h3><p>Another lesson is that the previous session may not have left the repo clean.</p><p>So every harness-generator session starts with orientation and baseline verification.</p><p>Before implementing anything, the agent must read the current sprint contract, feature list, progress log, and session handoff. Then it must verify that the project is already healthy.</p><p>That means running baseline commands like:</p><pre>adb devices<br>./gradlew assembleDebug<br>./gradlew testDebugUnitTest</pre><p>If the baseline is broken before the new work starts, the agent should not pretend the new feature caused it. It should record the state and fix or block appropriately.</p><p>At the end of the session, the agent must leave a clean exit.</p><p>Clean exit means more than “the app compiles.” It means:</p><ul><li>build passes</li><li>tests pass</li><li>quality gates pass</li><li>feature status is updated with evidence</li><li>temporary debug artifacts are cleaned up</li><li>session-handoff.md is updated</li><li>the next agent can continue from repo files alone</li></ul><p>This turns each session into a recoverable checkpoint.</p><h3>Lesson 3: Observability Belongs Inside The Harness</h3><p>A harness without observability forces the agent to guess.</p><p>When tests fail, the next question should not be “maybe it is timing?” The harness should expose enough runtime and process evidence to understand what happened.</p><p>In my project, I added observability rules in .agents/rules/observability.md.</p><p>The rules define:</p><ul><li>consistent android.util.Log usage</li><li>stable log tags</li><li>log levels for DEBUG, INFO, WARN, and ERROR</li><li>no PII in logs</li><li>what to inspect for API, Room, ViewModel, navigation, Hilt, and repository/cache issues</li><li>logcat filtering commands</li></ul><p>The implementation skill also reminds the agent to add structured logs at important state transitions and error boundaries.</p><p>This gives the next session better evidence. It can inspect state transitions, navigation events, cache decisions, recoverable failures, and runtime errors instead of guessing from code alone.</p><h3>The Power Of Looping: Create UI And Verify</h3><p>The create-ui-and-verify workflow is one of my favorite examples.</p><p>Even without advanced MCP tools, the agent can use a screenshot as feedback.</p><p>The loop is simple:</p><ol><li>Save the design screenshot under docs/current/design/.</li><li>Implement the UI.</li><li>Run build and static checks.</li><li>Run instrumented UI tests.</li><li>Capture an actual screenshot from the Android device or emulator.</li><li>Compare the actual screenshot against the original design.</li><li>Record deviations.</li><li>Fix the UI.</li><li>Repeat, up to the loop limit.</li></ol><p>This is powerful because it does not rely on the model being perfect in one shot.</p><p>The model can be smaller. The first attempt can be imperfect. The harness still improves the result through a feedback loop.</p><p>That is the deeper lesson of harness engineering: do not ask the model to be flawless. Build a system that lets the model try, observe, correct, and prove.</p><h3>Conclusion</h3><p>AI coding quality does not come from prompts alone.</p><p>It comes from a harness that breaks large work into slices, records evidence across sessions, refuses premature completion, verifies mechanically, and loops until the output matches the target.</p><p>The next stronger model will raise the ceiling. But without a harness, that extra capability still leaks away through overreach, lost context, missing verification, and messy handoffs.</p><p>My lesson from Android harness engineering is simple:</p><p>Do not wait for the next model.<br>Build the harness first.</p><h3>Explore the Harness</h3><p>The full harness — all workflows, stages, rules, skills, and gates — is available in the open-source NotesTakingApp project on GitHub: <a href="https://github.com/hwdavr/NotesTakingApp"><strong>NotesTakingApp</strong></a></p><p>The <em>.agents/</em> directory is the harness. Everything described in this article is there, ready to fork, adapt, and apply to your own project.</p><p>Sources:</p><ul><li>Anthropic: <a href="https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents">https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents</a></li><li>Learn Harness Engineering: <a href="https://walkinglabs.github.io/learn-harness-engineering/en/lectures/lecture-04-why-one-giant-instruction-file-fails/">https://walkinglabs.github.io/learn-harness-engineering/en/</a></li></ul><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=16af4f27775c" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[How to write automated tests for Certificate Pinning by using MockWebServer?]]></title>
            <link>https://weidianhuang.medium.com/how-to-write-automated-tests-for-certificate-pinning-by-using-mockwebserver-ace355506342?source=rss-865711e189d8------2</link>
            <guid isPermaLink="false">https://medium.com/p/ace355506342</guid>
            <category><![CDATA[android]]></category>
            <category><![CDATA[certificate-pinning]]></category>
            <category><![CDATA[mockwebserver]]></category>
            <dc:creator><![CDATA[Weidian Huang]]></dc:creator>
            <pubDate>Sun, 04 Apr 2021 15:57:50 GMT</pubDate>
            <atom:updated>2021-04-04T15:57:50.005Z</atom:updated>
            <content:encoded><![CDATA[<p>If you are using the certificate pinning in your Android app, you may have the same troubles as me:</p><ul><li>How to validate the implementation of the certificate pinning is correct?</li><li>How to validate the app’s behavior when the attacker tries to attack the app by using MiTM(Man in The Middle)?</li></ul><p>For the first trouble, OkHttp3 provided <strong>CertificatePinner</strong> to allow us to pin a server certificate with a few lines of code.</p><pre>val certificatePinner = <br>    CertificatePinner.Builder()<br>        .add(&quot;*.publicobject.com&quot;, &quot;sha256/AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=&quot;)<br>        .build();</pre><p>Although the implementation is simple, it doesn’t mean we don’t need to validate at all. There was one time in our app, we added one more certificate pin for a new server, the host waspublicobject.com , but the developer added as *.publicobject.com. In the end, that host was not pinned, and we only discovered it after one year. So there are 2 things we need to verify for this CertificatePinner:</p><ul><li>Whether the hostname set is correct?</li><li>Whether the certificate pin set is correct?</li></ul><h3>Validate Hostname</h3><p>To validate the hostname, I created this helper class.</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/848b513c32d9b9abbbda1fed250072a8/href">https://medium.com/media/848b513c32d9b9abbbda1fed250072a8/href</a></iframe><p>After that, we can use it inside the UrlInterceptor to check the request URL.</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/6cd028afdc4e17faf9086190f227a211/href">https://medium.com/media/6cd028afdc4e17faf9086190f227a211/href</a></iframe><p>We can also create some unit tests to automate this checking.</p><h3>Validate Certificate Pin</h3><p>Once the hostname is validated, the certificate pin validation is straightforward. We just need to create a normal instrumentation test and point to the real server. If the response is correct, the certificate pin should be correct also.</p><h3>Validate App behaviors when there is a MiMT attack</h3><p>This is the most challenging part of this article. In the normal way, we need to set up a proxy server and apply MiMT to do the testing. If we can have some automation tests to validate them, it can save some effort.</p><p>To achieve this, we need to use MockWebServer. If you want to know some basic usage of MockWebServer, please refer to another article from me.</p><p><a href="https://weidianhuang.medium.com/android-how-to-use-mockwebserver-for-edge-cases-test-automated-test-and-unit-test-together-3eb26e19ce68">Android: How to use MockWebServer for Edge-cases Test, Automated Test, and Unit Test together?</a></p><p>Basic MockWebServer is using http protocol only, to use https protocol, we need to call useHttps() to set up. The following example creates an SSL context by reading the key store from the app resources folder.</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/e04a02f62edffabdf2bd02e0fdcd5d32/href">https://medium.com/media/e04a02f62edffabdf2bd02e0fdcd5d32/href</a></iframe><p>Now we can use the SSL/TLS protocol with MockWebServer and we can apply certificate pinning to it also by adding the certificate pin for localhost.</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/73ccbd47176efd650a047292d6912c1f/href">https://medium.com/media/73ccbd47176efd650a047292d6912c1f/href</a></iframe><p>If the LOCAL_HOST_CERT_PIN here matches the key store we loaded from the resources folder previously, we can get the response from MockWebServer correctly, otherwise, we will get SSLHandshakeException.</p><p>In the automation test, we can start the server with different key stores to simulate both success and failure cases.</p><p>The last step we need to set up in the application is we need our app to trust the certificate from MockWebServer.</p><p>Firstly, we need to export the certificate from our key store by using the below command.</p><pre>keytool -export -alias localhost -keystore ./localhost.keystore.jks -file ../res/raw/certificate.cer -storetype BKS -provider org.bouncycastle.jce.provider.BouncyCastleProvider -providerpath /path/to/bouncycastle.jar</pre><p>The certificate will be exported to the app res/raw/ folder and we can trust it by setting in the network_security_config.xml file.</p><pre>&lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot; ?&gt;<br>&lt;network-security-config&gt;<br>    &lt;base-config cleartextTrafficPermitted=&quot;true&quot;&gt;<br>        &lt;trust-anchors&gt;<br>            &lt;certificates src=&quot;@raw/certificate&quot;/&gt;<br>            &lt;certificates src=&quot;system&quot;/&gt;<br>        &lt;/trust-anchors&gt;<br>    &lt;/base-config&gt;<br>&lt;/network-security-config&gt;</pre><p>All the details can be found in my sample app below:</p><p><a href="https://github.com/hwdavr/MockServerDemo">hwdavr/MockServerDemo</a></p><p>If you are using another method to implement certificate pinning instead of OkHttp, you can still use the same way to automate the test, just the details of the implementation may be slightly different.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=ace355506342" width="1" height="1" alt="">]]></content:encoded>
        </item>
    </channel>
</rss>