Harness engineering क्या है? Codex और Claude Code के लिए जाँची हुई गाइड

मान लीजिए किसी टीम ने AI एजेंट से repository व्यवस्थित करने को कहा। एजेंट ने काम से बाहर की configuration भी बदल दी और अंत में बस लिख दिया, “सभी टेस्ट पास हो गए।” अगर command, exit code और बदली गई फ़ाइलों की सीमा दर्ज नहीं है, तो इस दावे पर भरोसा करने का कोई ठोस आधार नहीं है।

समस्या केवल prompt के शब्दों में नहीं होती। एजेंट क्या पढ़ सकता है, कौन-से tools चला सकता है, किस स्थिति में रुकना है और काम पूरा होने का प्रमाण क्या होगा, यह भी तय करना पड़ता है। एजेंट के चारों ओर इस व्यवस्था को बनाना harness engineering कहलाता है। आसान भाषा में harness वह कार्य-ढाँचा है जो AI को उपयोगी काम करने देता है, लेकिन हर निर्णय अपने-आप लेने की छूट नहीं देता।

इस गाइड में पहले OpenAI की प्रकाशित Codex case study समझेंगे। फिर एक छोटा harness बनाएँगे जो फ़ाइल की सीमा लागू करता है, मौजूदा फ़ाइल को overwrite होने से रोकता है और बिना API खर्च के चलने वाला test देता है।

मुख्य बातें

• Harness कोई एक wrapper script नहीं है। इसमें repository की जानकारी, tools, permissions, tests, logs, recovery और मानवीय मंज़ूरी साथ काम करते हैं।
• OpenAI की Codex case study में repository की बनावट, application का व्यवहार और quality rules एजेंट के लिए पढ़ने और जाँचने योग्य बनाए गए।
• खोज, draft और दोहराए जाने वाले काम AI कर सकता है; deletion, production change, बाहरी संदेश और खर्च का फैसला इंसान के पास रहना चाहिए।
• Path के text prefix की जाँच पूरी sandbox नहीं है। Symbolic link, overwrite, process privilege और operating-system isolation भी ज़रूरी हैं।
• “Tested” लिखने से पहले command, result और scope दर्ज होना चाहिए। Model का success message प्रमाण नहीं है।

Harness engineering का सीधा अर्थ

Prompt बताता है कि इस बार क्या चाहिए। Harness तय करता है कि उस निर्देश पर काम किस वातावरण में होगा।

परत	यह कौन-सा सवाल हल करती है?	छोटा उदाहरण
Context	एजेंट क्या जान सकता है?	AGENTS.md, सीमित folder, versioned spec
Tools	एजेंट क्या कर सकता है?	पढ़ना, test चलाना, draft बनाना
Permissions	उसे कहाँ रुकना है?	Delete या send से पहले मानवीय मंज़ूरी
Verification	“पूरा” किसे मानेंगे?	npm test का exit code 0
Observability	गलती का कारण कैसे मिलेगा?	Command, diff और संबंधित error output
Recovery	खराब run को कैसे वापस करेंगे?	छोटे commits, dry-run और rollback steps

सिर्फ model बदलने से वह business rule सामने नहीं आएगा जो किसी व्यक्ति की याद में बंद है। इसके विपरीत, सही जानकारी repository में खोजने योग्य हो और acceptance criteria command से जाँचे जा सकें, तो एजेंट का काम अधिक भरोसेमंद बनता है।

2026 में चर्चा क्यों बढ़ी: OpenAI की Codex case study

इस विषय की मौजूदा चर्चा का एक प्रमुख स्रोत OpenAI का 11 फ़रवरी 2026 को प्रकाशित लेख Harness engineering: leveraging Codex in an agent-first world है।

OpenAI के अनुसार, तीन engineers ने Codex की मदद से लगभग पाँच महीनों में करीब 1,500 pull requests बनाए। केवल यह संख्या सीख नहीं है। अधिक महत्वपूर्ण यह है कि टीम ने काम का वातावरण इस अनुमान पर दोबारा बनाया कि implementation एजेंट करेंगे, न कि हर line इंसान स्वयं लिखेगा।

प्रकाशित तरीके में ये बातें शामिल थीं:

• plans और design decisions को version-controlled repository artifacts में रखना;
• UI, logs, metrics और traces को एजेंट के लिए सीधे inspect करने योग्य बनाना;
• dependency direction और दूसरी सीमाओं को structural tests और custom linters से लागू करना;
• failed run को किसी missing tool, rule या abstraction का संकेत मानना, केवल model से “और कोशिश” न करवाना;
• पुरानी documentation और जमा हुए drift को खोजने के लिए नियमित cleanup करना।

इसका मतलब बहुत लंबा system prompt बनाना नहीं है। Chat, बाहरी document या किसी व्यक्ति की स्मृति में छिपी जानकारी run के दौरान एजेंट को दिखाई नहीं देती। बेहतर तरीका है छोटा और स्थिर entry point, उससे जुड़ी focused sources और ऐसे checks जिन्हें अनदेखा न किया जा सके।

Claude Code में भी यही सोच लागू होती है। आधिकारिक Claude Agent SDK hooks documentation बताती है कि tool request को जाँचा, रोका, बदला या audit के लिए record किया जा सकता है। Product के controls अलग हो सकते हैं, पर boundary और feedback loop harness ही तय करता है।

AI को क्या दें और इंसान क्या तय करे

शुरुआत पूरी autonomy से न करें। पहले वे काम automate करें जिन्हें आसानी से वापस किया जा सकता है। ग्राहक, पैसे या production पर असर वाले कदम मंज़ूरी के बाद ही चलें।

शुरुआत में AI को दें	शर्त के साथ दें	इंसान का अंतिम फैसला
फ़ाइल खोजना	मौजूदा फ़ाइल बदलना	Production data मिटाना
Test चलाना	नई dependency जोड़ना	ग्राहक को e-mail भेजना
Diff का सार बनाना	Staging deploy करना	Billing या contract बदलना
Draft बनाना	Branch push करना	संवेदनशील personal data process करना

हर action पर दो सवाल पूछें: गलती होने पर इसे कम लागत में वापस किया जा सकता है? क्या इससे टीम के बाहर किसी व्यक्ति पर असर पड़ेगा? पहले read access और temporary output दें। किसी operation को automatic तभी करें जब उसके successful और failed दोनों cases दिखाई देते हों।

एक न्यूनतम harness बनाएँ

यह उदाहरण model को सिर्फ दो क्षमताएँ देता है:

1. sandbox के भीतर text पढ़ना;
2. sandbox के भीतर नई text file बनाना।

Delete, overwrite, shell और network का कोई tool नहीं दिया गया है। Sample को Node.js 22 पर जाँचा गया, और verification में उपयोग हुआ SDK version fixed रखा गया है।

mkdir harness-demo
cd harness-demo
npm init -y
npm install @anthropic-ai/[email protected]
mkdir sandbox
echo "# meeting notes" > sandbox/note.md

policy.json बनाएँ:

{
  "workspace": "./sandbox",
  "maxSteps": 6,
  "maxToolResultChars": 4000
}

1. फ़ाइल की सीमा code से लागू करें

safe-files.mjs बनाएँ। केवल candidate.startsWith(root) देखना पर्याप्त नहीं है: मिलते-जुलते नाम वाला folder match हो सकता है और workspace के भीतर symbolic link बाहर की जगह पर जा सकता है। नीचे read करते समय वास्तविक target जाँचा जाता है और write केवल नई फ़ाइल पर होती है।

import { open, readFile, realpath } from "node:fs/promises";
import path from "node:path";

function assertInside(root, candidate) {
  if (candidate !== root && !candidate.startsWith(root + path.sep)) {
    throw new Error(`outside workspace: ${candidate}`);
  }
}

export async function createFileGate(workspace) {
  const root = await realpath(path.resolve(workspace));

  async function readText(relativePath) {
    const requested = path.resolve(root, relativePath);
    assertInside(root, requested);
    const actual = await realpath(requested);
    assertInside(root, actual);
    return readFile(actual, "utf8");
  }

  async function createText(relativePath, content) {
    const requested = path.resolve(root, relativePath);
    assertInside(root, requested);
    const actualParent = await realpath(path.dirname(requested));
    assertInside(root, actualParent);

    let handle;
    try {
      handle = await open(requested, "wx", 0o600);
      await handle.writeFile(content, "utf8");
    } catch (error) {
      if (error.code === "EEXIST") {
        throw new Error(`refusing to overwrite: ${relativePath}`);
      }
      throw error;
    } finally {
      await handle?.close();
    }
    return "created";
  }

  return { readText, createText };
}

यह application-level guard है, पूरी security boundary नहीं। अधिक मजबूत isolation के लिए container, virtual machine, operating-system permissions या product की sandbox भी इस्तेमाल करें। Application check administrator privilege वाले process को निष्क्रिय नहीं करता।

2. Model को केवल दो tools दें

agent.mjs बनाएँ। Model का नाम article में स्थायी नहीं रखा गया है; account access और model availability बदल सकते हैं, इसलिए इसे ANTHROPIC_MODEL से लिया जाता है।

import Anthropic from "@anthropic-ai/sdk";
import { readFile } from "node:fs/promises";
import { createFileGate } from "./safe-files.mjs";

const model = process.env.ANTHROPIC_MODEL;
if (!model) throw new Error("Set ANTHROPIC_MODEL to a model available to your account.");

const policy = JSON.parse(await readFile("./policy.json", "utf8"));
const gate = await createFileGate(policy.workspace);
const client = new Anthropic();

const tools = [
  {
    name: "read_file",
    description: "Read a UTF-8 text file inside the workspace",
    input_schema: {
      type: "object",
      properties: { path: { type: "string" } },
      required: ["path"],
      additionalProperties: false
    }
  },
  {
    name: "create_file",
    description: "Create a new UTF-8 file; existing files cannot be overwritten",
    input_schema: {
      type: "object",
      properties: {
        path: { type: "string" },
        content: { type: "string" }
      },
      required: ["path", "content"],
      additionalProperties: false
    }
  }
];

async function runTool(name, input) {
  if (name === "read_file") return gate.readText(input.path);
  if (name === "create_file") return gate.createText(input.path, input.content);
  throw new Error(`unknown tool: ${name}`);
}

const prompt = process.argv.slice(2).join(" ") ||
  "Read note.md and create summary.md with a three-line summary.";
const messages = [{ role: "user", content: prompt }];

for (let step = 0; step < policy.maxSteps; step += 1) {
  const response = await client.messages.create({
    model,
    max_tokens: 1200,
    system: "Use only the supplied tools. Never claim a file was created unless the tool succeeded.",
    tools,
    messages
  });
  messages.push({ role: "assistant", content: response.content });

  const calls = response.content.filter((block) => block.type === "tool_use");
  if (calls.length === 0) {
    console.log(response.content.find((block) => block.type === "text")?.text ?? "done");
    process.exit(0);
  }

  const results = [];
  for (const call of calls) {
    try {
      const value = await runTool(call.name, call.input);
      results.push({
        type: "tool_result",
        tool_use_id: call.id,
        content: String(value).slice(0, policy.maxToolResultChars)
      });
    } catch (error) {
      results.push({
        type: "tool_result",
        tool_use_id: call.id,
        is_error: true,
        content: error.message
      });
    }
  }
  messages.push({ role: "user", content: results });
}

throw new Error(`step limit exceeded: ${policy.maxSteps}`);

3. Model बुलाने से पहले guard का test करें

महत्वपूर्ण boundary को API credits खर्च किए बिना local machine पर जाँचा जा सकता है। safe-files.test.mjs बनाएँ:

import assert from "node:assert/strict";
import test from "node:test";
import { mkdtemp, mkdir, rm, symlink, writeFile } from "node:fs/promises";
import { tmpdir } from "node:os";
import path from "node:path";
import { createFileGate } from "./safe-files.mjs";

test("file gate blocks traversal, overwrite, and outside symlinks", async () => {
  const base = await mkdtemp(path.join(tmpdir(), "harness-test-"));
  const root = path.join(base, "sandbox");
  const outside = path.join(base, "outside.txt");

  try {
    await mkdir(root);
    await writeFile(path.join(root, "note.md"), "hello", "utf8");
    await writeFile(outside, "secret", "utf8");
    const gate = await createFileGate(root);

    assert.equal(await gate.readText("note.md"), "hello");
    await assert.rejects(() => gate.readText("../outside.txt"), /outside workspace/);
    await assert.rejects(() => gate.createText("note.md", "replace"), /refusing to overwrite/);

    try {
      await symlink(outside, path.join(root, "outside-link.txt"), "file");
      await assert.rejects(() => gate.readText("outside-link.txt"), /outside workspace/);
    } catch (error) {
      if (error.code !== "EPERM") throw error;
    }

    assert.equal(await gate.createText("summary.md", "safe"), "created");
  } finally {
    await rm(base, { recursive: true, force: true });
  }
});

Offline checks चलाएँ:

node --test safe-files.test.mjs
node --check agent.mjs

इसके बाद ही ANTHROPIC_API_KEY और ANTHROPIC_MODEL set करके node agent.mjs चलाएँ। Credentials को source control या policy.json में न रखें।

तीन उपयोग के मामले

1. Software team: pull request बनाना और जाँचना

एजेंट को focused issue, संबंधित directories और test commands दें। “Code लिख दिया” acceptance condition नहीं है। पहले failure reproduce हो, fix के बाद test pass हो और diff समझने योग्य हो। Production deploy और migration पर मानवीय approval रखें।

2. Content operation: कमजोर article को publish होने से रोकना

लेखन और quality gate को अलग रखें। Duplicate topic, depth, code syntax, links और mobile layout के checks चलाएँ। कोई check fail हो तो publication रोकें और अगली correction साफ़ बताएँ। इस तरह “article तैयार है” कहने वाला output मशीन की जाँच की जगह नहीं लेता।

3. Customer support: inquiry classify करके reply draft बनाना

एजेंट संदेश को category दे सकता है और कारण सहित reply draft तैयार कर सकता है। Customer record में बदलाव और असली send इंसान मंज़ूर करे। केवल ज़रूरी personal information दें और पूरा message long-term logs में न रखें।

ROI का सरल हिसाब

Generated tokens नहीं, मानवीय review time और rework मापें। उदाहरण के लिए, हर सप्ताह 15 tasks पर 20 मिनट review लगता है तो कुल पाँच घंटे लगते हैं। Harness बनाने में छह घंटे और weekly maintenance में एक घंटा लगे, तो शुरुआती लागत लगभग डेढ़ सप्ताह में वापस आ सकती है।

यह समझाने के लिए गणना है, guaranteed result नहीं। लागू करने से पहले और बाद में दो-दो सप्ताह ये आँकड़े लें:

• हर task पर इंसान के मिनट;
• rework rate;
• production से पहले पकड़े गए defects;
• मानवीय approval के लिए escalations की संख्या।

बहुत अधिक approvals का अर्थ हो सकता है कि किसी proven low-risk operation को और संकरे दायरे में automate किया जा सकता है। Defects बढ़ें तो autonomy बढ़ाने के बजाय नया check या बेहतर context जोड़ें।

Pitfalls: आम गलतियाँ और सुधार

Folder के नाम की जाँच को sandbox मान लेना

Path अंदर दिखाई दे सकता है, जबकि symbolic link का वास्तविक target बाहर हो। Real target resolve करें, overwrite रोकें और operating-system permissions को दूसरी boundary बनाएँ।

Prompt में केवल “खतरनाक काम मत करना” लिखना

Text मार्गदर्शन देता है, enforcement नहीं। Dangerous tool दें ही नहीं या pre-tool hook में उसे deny करें। Claude Code permissions guide में एक ठोस configuration देख सकते हैं।

Model के “tests pass” संदेश को प्रमाण मानना

Command, exit status और verification scope record करें। UI के काम में direct interaction या screenshot evidence भी चाहिए। Verification receipt workflow इन प्रमाणों को सुरक्षित रखने का तरीका बताता है।

हर run में हर document भेजना

लंबा context सबसे महत्वपूर्ण सीमा को दबा सकता है। छोटा entry point दें जो focused, versioned sources तक ले जाए। Freshness और verification status लिखें ताकि पुरानी documentation मिल सके।

अगला कदम

एक reversible workflow चुनें और चार पंक्तियाँ लिखें: input, allowed actions, acceptance command और human-approval actions। वास्तविक repository में permissions, verification और review gates लगाने के लिए Claude Code प्रशिक्षण और implementation consultation का उपयोग करें।

वास्तव में क्या जाँचा गया

21 जुलाई 2026 को इस article के safe-files.mjs और safe-files.test.mjs blocks temporary directory में निकाले गए और Node.js से चलाए गए। Fixture ने सामान्य read, नई file creation, ../ traversal rejection और overwrite rejection की जाँच की। जिन systems पर test process symbolic link बना सकता है, वहाँ बाहर की ओर जाने वाले link को रोकना भी जाँचा जाता है। agent.mjs पर syntax check किया गया।

Live Anthropic API call इस verification scope में शामिल नहीं है, क्योंकि model access और cost account के अनुसार बदलते हैं। “Code प्रकाशित है”, “syntax checked है”, “offline test चला है” और “paid external API call हुई है” चार अलग दावे हैं। भरोसेमंद harness दर्ज करता है कि इनमें से कौन-सा दावा सच है।