Harness Engineering: Building Stable AI Agents

The Four Pillars in Detail

1. Constrain: Setting Boundaries

AI without constraints acts like an unchecked assistant—more confident, less accurate. Define explicit guardrails:

constraints:
  forbidden:
    - delete_files
    - force_push
    - update_dependencies
    - modify_permissions
  allowed:
    - add_comments
    - suggest_changes
    - propose_refactoring
    - request_fixes

Without constraints, AI optimizes for "doing more," leading to over-aggressive modifications and cascading failures.

2. Inform: Providing Context

Give the AI only the information it needs to make good decisions. Excessive or irrelevant context creates noise; missing context causes errors.

const reviewContext = {
  file: "src/auth/login.ts",
  language: "typescript",
  diff: "<unified diff>",
  
  // Project context
  standards: {
    linter: "ESLint Airbnb",
    minCoverage: 80,
    security: "OWASP Top 10",
  },
  
  // Test results
  tests: {
    unit: "PASS",
    types: "PASS",
    security: "FAIL (1 medium)",
  },
  
  // Recent history
  recentCommits: [
    "fix: SQL injection",
    "feat: MFA support",
  ],
};

3. Verify: Automated Validation

Run your verification suite on AI outputs before accepting them:

#!/bin/bash
set -e
 
echo "Verification suite..."
 
npx eslint . --fix
npx tsc --noEmit
npm test -- --coverage
npx snyk test --severity-threshold=high
 
echo "✓ All checks passed"

If verification fails, feed the errors back to the AI for correction rather than rejecting outright.

4. Correct: Automated Repair

When verification fails, let the AI try to fix it:

async function autoReview(changes: string): Promise<void> {
  let attempts = 0;
  const maxAttempts = 3;
  
  while (attempts < maxAttempts) {
    const validation = await verify(changes);
    
    if (validation.passed) {
      console.log("✓ Validation passed");
      return;
    }
    
    console.log(`Attempt ${attempts + 1}: Fixing errors...`);
    changes = await ai.fixErrors({
      code: changes,
      errors: validation.failures,
      constraints: constraints,
    });
    
    attempts++;
  }
  
  console.log("✗ Max attempts reached, requires human review");
}

Complete 5-Step Automated Review Pipeline

Step 1: Monitor and Trigger

import { Octokit } from "@octokit/rest";
 
const octokit = new Octokit({ auth: process.env.GITHUB_TOKEN });
 
async function onPROpened(owner: string, repo: string, prNumber: number) {
  const pr = await octokit.pulls.get({ owner, repo, pull_number: prNumber });
  console.log(`Reviewing PR #${prNumber}: ${pr.data.title}`);
  await performReview(owner, repo, prNumber);
}

Step 2: Gather Context

async function gatherContext(owner: string, repo: string, prNumber: number) {
  const { data: files } = await octokit.pulls.listFiles({
    owner, repo, pull_number: prNumber,
  });
  
  return {
    files: files.map(f => ({
      name: f.filename,
      diff: f.patch,
      additions: f.additions,
      deletions: f.deletions,
    })),
    projectStandards: await loadProjectConfig(),
    testResults: await runTests(),
  };
}

Step 3: AI Initial Review

async function reviewWithAI(context: any) {
  const prompt = `
Review these changes:
${context.files.map(f => `${f.name}:\n${f.diff}`).join("\n---\n")}
 
Project standards: ${JSON.stringify(context.projectStandards)}
Test results: ${JSON.stringify(context.testResults)}
 
Report issues as JSON:
[{
  severity: "CRITICAL|HIGH|MEDIUM|LOW",
  type: "security|performance|test|style",
  line: <number>,
  suggestion: "<human-readable fix>"
}]
  `;
  
  return await ai.analyze(prompt);
}

Step 4: Verification

#!/bin/bash
verify() {
  npm run lint && \
  npm run typecheck && \
  npm test -- --coverage && \
  npx snyk test
}
 
if verify; then
  echo "✓ Verification passed"
  exit 0
else
  echo "✗ Verification failed"
  exit 1
fi

Step 5: Fix and Comment

async function fixAndComment(owner: string, repo: string, prNumber: number, issues: any[]) {
  const critical = issues.filter(i => ["CRITICAL", "HIGH"].includes(i.severity));
  
  if (critical.length === 0) {
    console.log("No critical issues");
    return;
  }
  
  const fixPrompt = `
Critical issues found:
${critical.map(i => `- ${i.suggestion}`).join("\n")}
 
Generate a fix that passes all tests and linters.
  `;
  
  const proposedFix = await ai.generateFix(fixPrompt);
  
  // Verify the fix
  if (await verify(proposedFix)) {
    // Create PR comment with results
    await octokit.issues.createComment({
      owner, repo, issue_number: prNumber,
      body: `## 🤖 Code Review\n\n${formatIssues(issues)}`,
    });
  }
}

Common Pitfalls and Solutions

Pitfall 1: Over-Specification

Problem: AI generates too many low-value suggestions, overwhelming reviewers.

Solution: Filter by severity

CRITICAL:  # Block merge
  - Security vulnerabilities
  - Test failures
HIGH:      # Comment + request
  - Performance issues
  - Major violations
MEDIUM:    # Comment only
  - Style improvements
LOW:       # Ignore
  - Spelling, formatting

Pitfall 2: Oscillation

Problem: AI cycles between A → B → A, never converging.

Solution: Track modification history

const modified = new Set<string>();
 
function canModify(filename: string, line: number): boolean {
  const key = `${filename}:${line}`;
  if (modified.has(key)) return false;
  modified.add(key);
  return true;
}

Pitfall 3: Privilege Escalation

Problem: AI performs unauthorized operations.

Solution: Pre-execution validation

FORBIDDEN=(
  "rm -rf"
  "git push --force"
  "npm update -g"
  "sudo"
)
 
for cmd in "${FORBIDDEN[@]}"; do
  grep -q "$cmd" proposed_changes.txt && exit 1
done

Antigravity 2.0 and the CLI Share One Harness

The recent direction of Antigravity fits harness engineering unusually well. Antigravity 2.0 spans several surfaces—a desktop app, a CLI, an SDK, and a Managed Agents API—and the new Antigravity CLI is designed to share the same agent harness as the rest, so core agent improvements propagate to every surface automatically.

What I care about here is keeping my side of the harness—constraints and verification—decoupled from any single UI. If Constrain and Verify live in the repository as artifacts (an AGENTS.md, a set of pre-push scripts), then whether the entry point is the desktop app or the terminal, the same safety net applies unchanged.

With the migration from Gemini CLI to Antigravity CLI in the air, this paid off concretely: the entry-point tool changed, but the harness sitting in the repo did not need to be rebuilt. Leave making the agent smarter to the vendor; keep "what it must not do" and "the checks it must pass" as your own durable assets. That division of labor is what keeps you from being whipped around by tool generations.

What the Harness Is Worth: Numbers From Running Four Sites

As an indie developer at Dolice, I run several technical blogs in parallel and hand the generate-to-push flow to agents. The lesson that stuck: most accidents are stopped by verification, not by intelligence.

The checks I run before every push are just a handful of scripts—internal-link integrity, frontmatter validity, a machine check of robots.txt. Even so, roughly 80% of the cases that forced a redo were caught at that verification stage, leaving about 20% to escalate to a human.

Verification scripts aren't free, of course. Each one adds maintenance: tuning out false positives, keeping up with spec changes. My rule is simple—only promote a check to a blocking gate if it guards against the kind of failure that hurts once it ships. Cosmetic issues stay as warnings; only hard-to-reverse problems like broken links or corrupted config earn the right to stop the work.

Deciding How Tight to Constrain

The first hard question in Constrain is granularity. Too tight and the agent can't do useful work; too loose and accidents slip through. Where I landed was to split by whether an action is reversible:

Once I drew this line, I stopped needing to enumerate constraints in fine detail. Name the irreversible operations explicitly, delegate the rest to verification—and new operations no longer create new decisions. Reversible failures can simply be redone; only irreversible ones are truly frightening. The constraint list is just that ordinary instinct, translated.

The Human Role

Harness engineering doesn't eliminate human judgment—it redirects it:

• Design the harness: Decide what the AI should and shouldn't do
• Make hard calls: When CRITICAL issues conflict, humans decide
• Monitor emergence: Watch for patterns the harness didn't anticipate

Humans become decision-makers and architects, not reviewers.

Conclusion

Harness engineering transforms AI from a "risky automation tool" into a "reliable team member." The four pillars—constraint, information, verification, correction—create a self-improving system that adapts to your project without requiring constant human oversight.

The key insight: AI's value comes from environment design, not raw intelligence.

As a first step, skip building all four pillars and add only Verify today: bundle lint, type checks, and tests into one script and run it after every agent task. That alone stops most accidents at the checkpoint. Constraints and auto-correction can come later, once verification is humming.