Why Knowledge, Not Harness, Is the Real Moat: Designing a Layered Knowledge Architecture for AI Engineering Teams

Harness Engineering Overview

At the end of 2025 a wave of discussion around Harness Engineering emerged. The term uses the metaphor of a horse’s harness: the rider controls the horse’s power rather than increasing the horse’s muscles. The focus is on guiding and constraining AI model capabilities instead of merely scaling model size.

Flagship practices

OpenAI – Codex : human‑AI protocol that uses zero‑code instructions to steer agents.

Cursor – Self‑Driving : multi‑agent coordination where background agents automatically detect conflicts and run tests.

Anthropic – Claude Code : long‑term stability achieved with multi‑level memory and CLAUDE.md constraints to keep agents consistent on complex tasks.

These practices are exciting, but the deeper insight from the team’s experience is that workflows are merely pipelines; knowledge is the flowing water. A round‑table quote captured the core belief: “Future technical moats will lie in vertical‑domain knowledge, not in the model itself.”

Core Argument: Knowledge Deposition Beats Workflow Design

Workflows are replaceable, knowledge is cumulative

Today the team uses a 16‑stage state‑machine; tomorrow the same process could be expressed as a DAG or another graph, and agent scheduling may shift from serial to parallel or hierarchical. Model upgrades and tool‑chain changes happen quickly. However, concrete knowledge—e.g., “advertising‑budget deduction can over‑deduct under high concurrency; use Redis+Lua for atomicity”—remains valuable regardless of workflow changes.

Workflows without knowledge are one‑shot

When a complex agent pipeline is rebuilt for each new request, the same pitfalls and architectural decisions are repeated. Without a knowledge loop the toolchain never becomes smarter.

Knowledge as a team’s compound asset

Knowledge is classified into three categories:

Scatter knowledge : isolated facts.

Causal knowledge : A → B reasoning chains.

Spatiotemporal knowledge : context‑specific experience that only holds in certain scenarios or time windows.

When a repository contains hundreds of proven entries, newcomers and new projects can “stand on the shoulders of predecessors,” creating a compound‑interest effect.

Three Pillars of Harness Engineering

┌─────────────────────────────────────┐
│        Harness Engineering Pillars   │
├─────────────┬─────────────┬─────────┤
│ Context Eng │ Architecture │ Governance │
│ (Long/short‑term memory,      │ (Agent orchestration, │ (Quality gate,      │
│  knowledge retrieval)         │ state‑machine design)│  knowledge lifecycle)│
└─────────────┴─────────────┴─────────┘

The Context Engineering pillar explicitly lists knowledge retrieval injection and long/short‑term memory . The Governance pillar includes knowledge lifecycle and automatic decay . Therefore knowledge management is the central capability of Harness Engineering, not an after‑thought.

Layered Knowledge Architecture

Three orthogonal dimensions

Storage layer (where) : defines where knowledge is stored – Layer 0‑P (personal), Layer 0‑T (team), Layer 1 (technical), Layer 2 (business), Layer 3 (project).

Knowledge type (what) : describes what the knowledge is – model , decision , guideline , pitfall , process .

Maturity (how trusted) : indicates how many validations – draft → verified → proven.

Five‑layer storage blueprint

┌───────────────────────────────────────┐
│          Five‑Layer Knowledge Store    │
├───────┬───────────────────────┬───────┤
│ Layer 0‑P │ personal preferences (~/.ai‑team/) │ local, not shared │
│ Layer 0‑T │ team conventions (team‑conventions/) │ Git‑shared │
│ Layer 1   │ technical knowledge (tech‑wiki/) │ cross‑project │
│ Layer 2   │ business knowledge (biz‑wiki/{domain}/) │ domain‑specific │
│ Layer 3   │ project knowledge (docs/knowledge/) │ project‑only │
└───────┴───────────────────────┴───────┘

Why five layers? Each layer defines a different sharing boundary and lifecycle:

Layer 0‑P (personal): e.g., 2‑space vs 4‑space indentation, coding style preferences.

Layer 0‑T (team): coding standards, commit policies, review guidelines.

Layer 1 (technical): reusable patterns such as “Spring Boot multi‑tenant interceptor.”

Layer 2 (business): domain models and rules, e.g., “ad review flow: submit → auto‑review → manual‑review → launch.”

Layer 3 (project): project‑specific context, e.g., “this project uses TencentDB for MySQL 8.0.”

Knowledge can be promoted upward: a project‑level entry that proves useful across projects is automatically lifted to Layer 1 or 2.

Layer 3 (project) →
  ├─ Q1: Is it project‑specific? → keep in Layer 3
  ├─ Q2: Is it a generic technique? → promote to Layer 1
  └─ Q3: Is it a generic business rule? → promote to Layer 2

Five knowledge types (MECE)

model : entity definition, data schema, relationship diagram. Example – “Ad plan contains budget, bid, and schedule fields.”

decision : technical choice and rationale. Example – “Choose event‑driven over RPC sync because ad‑status changes need decoupling.”

guideline : recommended (avoid) practices. Example – “recommend: compatibility checklist after changing a public module.”

pitfall : known risk or failure mode. Example – “Ad budget deduction may over‑deduct under high concurrency.”

process : business flow or state‑machine step. Example – “Ad review: submit → auto‑review → manual‑review → launch.”

Each entry belongs to exactly one type; provenance metadata records its source for traceability.

Three‑stage maturity + automatic decay

draft (new, single source) →
  used in ≥1 workflow → verified (single‑project validated) →
  used in ≥2 projects → proven (trusted)

Decay rules:
- proven not referenced for 12 months → downgrade to verified
- verified not referenced for 6 months → downgrade to draft
- draft never referenced + lint flag → archive (remove from active index)

Knowledge is not “write‑once‑done.” Over time unused entries decay, preventing stale or contradictory information from polluting the system.

Team Knowledge Base: Shared and Updatable

Independent Git repository as a single source of truth

team-knowledge.git
├── knowledge-catalog.md          # panoramic index (Agent query entry)
├── .knowledge-config.yaml       # members, conflict policy
├── team-conventions/            # Layer 0‑T
│   ├── coding-standards.md
│   └── commit-conventions.md
├── tech-wiki/                   # Layer 1
│   ├── catalog.md
│   ├── patterns/TK-PAT-001.md
│   └── anti-patterns/TK-AP-001.md
├── biz-wiki/                    # Layer 2
│   └── {domain}/
│       ├── catalog.md
│       ├── entities/BK-AD-E001.md
│       └── pitfalls/BK-AD-P001.md
├── project-profiles/
└── contributions/
    ├── pending/
    └── conflicts/

Why a separate repo?

Cross‑project sharing – knowledge from Project A benefits Project B automatically.

Lifecycle independence – even if a codebase is archived, its knowledge persists.

Permission independence – access control can differ from code repositories.

Three team roles

maintainer : resolves conflicts, approves maturity upgrades, manages members.

contributor : adds knowledge via workflow (create, verify, mark conflicts).

reader : consumes only (query/inject), no write rights.

Contribution model – append‑only log + traceability

Every change is recorded in an immutable log.md that captures contributor, timestamp, and session hash, similar to Git’s blame at the knowledge‑item level.

## [2026-04-09] ingest | [Steven] | Store fulfillment view archive | +1 decision, +2 guideline | #a3f8c2
- New DEC-005: map component selection (Tencent Map GL JS SDK)
- New GL-012: flexbox‑compatible fitBounds alternative (recommend)

## [2026-04-12] verify | [Alice] | Cross‑project validation | maturity↑ 2 | #c5f0e2
- TK-SB-003: "Pagination query latency optimization" (verified→proven, 2 projects)

Conflict‑resolution strategy

Pure addition (different IDs) : auto‑merge, keep both.

Evidence addition (same ID, new proof) : auto‑merge, deduplicate evidence array.

Maturity upgrade : auto‑merge.

Content contradiction : write to contributions/conflicts/ and notify maintainer.

Maturity clash (one up, one down) : keep lower maturity, mark as contradiction.

Most cases are handled automatically; only genuine content contradictions require human arbitration, keeping co‑creation friction low.

Workflow Integration: Knowledge Deposition in Action

Full knowledge lifecycle – three channels

/flow-import   (cold‑start)   →   /flow-run (per‑request)
      │                               │
      ▼                               ▼
Cold‑start import          INIT: git pull knowledge repo
3 Agent pipeline            → knowledge written to team repo
                              → Agents query as needed (progressive index)
                              ↓
ARCHIVE: extract decisions, pitfalls, guidelines → auto‑promote maturity

Three critical moments:

INIT (knowledge injection) : workflow start triggers git pull of the knowledge repo, giving every new run the full panoramic catalog.

Execution (knowledge consumption) : agents query the repo at decision points, e.g., @tech-explorer looks for similar architecture decisions, @backend-architect fetches known anti‑patterns.

ARCHIVE (knowledge extraction) : after workflow finishes, @archiver converts artefacts into structured knowledge entries (decision, pitfall, guideline) and runs maturity‑upgrade logic.

Stage‑specific query focus

ANALYSE_PRODUCT : business knowledge (Layer 2) + historic requirements → model, process, pitfall.

ANALYSE_TECH : technical knowledge (Layer 1) + archive index → decision, guideline (avoid), pitfall.

ARCHITECT : architecture patterns + entity relationships → decision, model.

IMPLEMENT : coding practice + team conventions → guideline, pitfall.

BUILD_VERIFY : anti‑pattern library → pitfall, guideline (avoid).

Query budgets prevent agents from pulling the entire knowledge base, avoiding context bloat.

Remote control – breaking the “on‑desk” bottleneck

Agents often stall at human‑approval nodes because developers are in meetings, commuting, or eating. To keep the pipeline alive, the team introduced Hapi (intranet edition) with the following capabilities:

Cross‑device session takeover : phone, tablet, or PC can hijack the same Agent session, so workflow never stops due to device switch.

24‑hour standby : Agent runs continuously on the development machine, enabling 7×24 h flow.

PWA native experience : installable as a desktop app, lowering the barrier for remote control.

Multi‑assistant switching : supports Codebuddy, Codex, Gemini, etc., making the system engine‑agnostic.

Autonomous mode : YOLO mode lets Agent act without human confirmation, reducing manual approval frequency.

With remote control, fragmented time (meeting gaps, commute) can be used to approve or review steps via phone, dramatically shortening delivery cycles and keeping the knowledge‑extraction phase timely.

Practical Experience and Reflections

Cold‑start for legacy projects

Turning implicit knowledge into explicit entries required a three‑step approach:

Multi‑source collection via /flow-import (Git, TAPD, iWiki, local docs, voice).

Gradual import – all items start as draft (confidence 0.5‑0.6) and mature through real workflow usage.

Checkpoint persistence with import-state.json to resume after interruptions.

Knowledge bloat management – Lint mechanism

Inspired by Karpathy’s LLM‑Wiki, a periodic lint runs to keep the repo healthy. Checks include index inconsistency (auto‑fix), orphan entries (downgrade to draft), contradiction detection (mark conflict), staleness (archive drafts unused >6 months), duplicate/similar entries (mark as merge candidate), and maturity decay (apply automatic downgrade rules). Linter triggers automatically after every ten workflows, on manual /knowledge lint, or when a workflow starts after 30 days of inactivity.

Big model vs. big harness – a pragmatic stance

Model upgrades are inevitable; the knowledge layer should stay open to benefit from stronger models.

Model strength cannot replace domain‑specific knowledge – only the team’s accumulated experience knows hidden business pitfalls.

Investing in knowledge yields deterministic ROI: each proven entry benefits all future workflows, whereas model improvements are probabilistic.

File‑system‑as‑state machine

All state, artefacts, and knowledge live as plain Markdown files in a Git repo—no separate database or platform. Benefits include visibility (anyone can read/edit), versionability (Git history), portability (knowledge can be moved to any toolchain), and IDE native support (the .codebuddy/ directory is recognized by editors without extra configuration).

Summary and Outlook

Layered knowledge management (five storage layers × five types × three maturity levels) gives agents precise, on‑demand access.

Independent Git‑backed knowledge base with clear roles turns personal experience into a team asset.

Workflow integration (INIT → consumption → ARCHIVE) makes every delivery a knowledge‑building event.

Progressive three‑stage index and query budget balance context size and relevance.

Automatic decay, linting, and reference tracking keep the repository healthy.

Remote‑control and asynchronous approvals eliminate the “human‑in‑the‑room” bottleneck, enabling 24/7 flow.

Future directions include semantic vector search, cross‑team knowledge federation, automated quality scoring of entries, and fully asynchronous human‑AI collaboration.

Skill, Agent, and toolchain evolve with model upgrades, but domain knowledge endures. Each AI Team delivery automatically deposits knowledge into a shared repository, letting every new workflow start on the shoulders of its predecessors.

References:

Andrej Karpathy, “LLM Wiki – Ingest + Query + Lint.”