Part 5 — Encoding domain knowledge

You’ve built the infrastructure. Now comes the harder question: how do you give the agent genuine knowledge of how your organization works? Not generic knowledge — your conventions, your regulatory requirements, your codebase structure. This section covers the three-layer approach to encoding that knowledge, the cross-vendor standard for instruction files, and why AST-based code search is no longer optional.

Q5.1 — How do I capture our organizational patterns and domain knowledge into the harness?

Three layers, used together — and the layering is the answer:

1. 1.

   Lean instruction memory (CLAUDE.md / AGENTS.md / .github/copilot-instructions.md) — only what’s always true and unguessable. Kept under roughly 200–300 lines, for the reasons covered in Q1.3. This is the always-on layer.

2. 2.

   Skills for specialized expertise — one skill per recurring task: code-review, secure-coding-checklist, db-migration, pii-handling, regulatory-logging, incident-runbook, plus genuinely domain-specific ones (payments, kyc, clinical-data). Each is discovered by its description and loaded only when relevant.

3. 3.

   MCP servers for live systems — wire Jira, Confluence, the internal API gateway, observability (Datadog/Sentry), and the design system into MCP servers, exposed only through the managed allowlist. This is how the agent gets current organizational reality rather than a stale document.

The discipline: ask of every piece of knowledge, “is this always relevant, situationally relevant, or live?” — and route it to layer 1, 2, or 3 accordingly. If you find yourself putting a 200-line checklist into CLAUDE.md, that’s a skill waiting to be written.

Q5.2 — AGENTS.md vs CLAUDE.md vs copilot-instructions.md — which one is the standard?

AGENTS.md is the cross-vendor standard, now stewarded by the Agentic AI Foundation under the Linux Foundation. Since its August 2025 release it has been adopted by 60,000+ open-source projects and by agent tools including Codex, Cursor, Devin, Gemini CLI, GitHub Copilot, Jules, and VS Code.

The recommended pattern for a multi-vendor org:

• Maintain one canonical AGENTS.md with your org-wide and repo-wide context.
• Make CLAUDE.md a thin file that @AGENTS.md-imports it and adds only Claude-specific overrides. (As of Q2 2026, Claude Code does not read AGENTS.md directly — the @import or a symlink is the bridge.)
• Have .github/copilot-instructions.mdreference or re-state the same content for Copilot’s repo-wide layer, keeping the first 4,000 characters dense for code-review compatibility.

This gives you a single source of truth with thin per-vendor adapters — exactly the shape of the whole harness.

Q5.3 — Why replace grep with AST/graph code search, and what do I actually deploy?

Grep matches text; it doesn’t understand structure. When an agent asks “who calls this function” or “what’s the type of this symbol,” grep returns noise and the agent burns tokens reading files to disambiguate. AST/graph search answers structurally and cheaply:

• CocoIndex reports around 70% fewer tokens per turn for code search tasks
• CodeGraphContext reports up to a 120x token reduction on structural queries like finding callers

The baseline is already in the box: Anthropic’s official marketplace ships 12 language-server “code intelligence” plugins (jump-to-definition, find-references, call hierarchies via LSP). Enable those for every primary language first.

Then layer a specialized AST/graph MCP server on top, chosen for your needs:

• CocoIndex Code — Tree-sitter AST-aware semantic search; one-line install (claude mcp add cocoindex-code -- ccc mcp)
• Code Pathfinder — 5-pass AST analysis with call-graph and dataflow tracking; runs locally; Apache-2.0
• CodeGraphContext — explicit knowledge graphs built from the AST
• ast-grep-mcp — exposes structural search and YAML rules as MCP tools; good for enforcing code policy at scale
• flupkede/codesearch — Rust, multi-repo, hybrid vector + BM25, fully offline; built for enterprise polyrepo
• Claude Context (Zilliz) — Milvus-backed, supports local embeddings (Ollama) for an air-gapped stack

For a regulated polyrepo: deploy one such server per language family inside your VPC, index the repo set nightly, and expose it through the managed MCP allowlist so every Claude Code and Copilot CLI session hits the same shared index.

Q5.4 — Everyone's blogging their own version of this. What's the actual 2026 consensus?

By mid-2026 a recognizable consensus emerged across Anthropic’s engineering posts, the Thoughtworks Technology Radar, HumanLayer, Pixelmojo, PubNub, and others. Eight points:

1. 1.Treat the harness as engineering, not configuration — months of platform-team time, then continuous maintenance.
2. 2.Lean CLAUDE.md, thick skill library — push detail into auto-discovered skills.
3. 3.Progressive disclosure is a system-design pattern — the three-layer loading model now applies even to non-coding agents.
4. 4.AST/graph search replaces grep — once novel, now expected.
5. 5.Subagent pipelines with context forking — pm-spec → architect-review → implementer-tester, with noisy work forked off.
6. 6.Hooks as the deterministic control layer — rules without hooks are advisory.
7. 7.Private plugin marketplaces become the org's internal AI app store.
8. 8.AGENTS.md as the cross-vendor standard — one canonical file, thin per-tool overrides.

If your design contradicts several of these, that’s worth a second look. Not because consensus is always right, but because each of these points was learned by people who shipped real systems and ran into the alternative.