Skip to content

The Implicit Knowledge Problem

Knowledge living only in Slack threads, meetings, or team memory is invisible to agents -- producing repeating errors that no prompting can fix.

The Pattern

Team conventions, architectural decisions, and domain rules live in Slack threads, meeting recordings, and institutional memory. An agent violates a rule, the developer corrects it, and the next session repeats the mistake. This is a knowledge externalization problem: each session is a recurring first day with no access to accumulated decisions (Hodgson).

Why It Fails Silently

Each session starts fresh: no persistent memory of prior sessions, established conventions, or past mistakes (Vasilopoulos). Without explicit conventions, agents default to training-data patterns — broad programming knowledge that may contradict project requirements. The output compiles, passes review, and ships. Across 283 sessions on a 108k-line system, missing specs caused silent failures — wrong decisions that looked correct, never surfaced as errors.

What Knowledge Is Invisible

Knowledge type Example Where it actually lives
Architectural decisions "We chose Postgres over DynamoDB because..." Slack thread from 6 months ago
Naming conventions "Services use -handler suffix, not -service" A developer's memory
Deployment constraints "Never deploy feature X on Fridays" Verbal agreement in standup
API design taste "We prefer query params over path params for filters" Code review comment patterns
Tech debt boundaries "Don't extend module Y -- it's being replaced" A Jira ticket nobody reads

Remediation

graph LR
    A["Decision Docs<br/>(version-controlled)"] --> B["Instruction Files<br/>(AGENTS.md / CLAUDE.md)"]
    B --> C["Mechanical Enforcement<br/>(linters, CI, hooks)"]
    C -->|"fail signal"| D["Agent corrects"]
    A -->|"context"| D

1. Version-controlled decision artifacts

Push design docs, execution plans, and tech debt trackers into the repository. If it is not in version control, it does not exist for agents (Lavaee).

2. Instruction files for non-discoverable context

Use AGENTS.md, CLAUDE.md, or equivalent files to capture conventions not inferable from code. Keep them thin -- entry points to reference directories, not monolithic documents (Lavaee).

Distinguish from discoverable context

Only include what agents cannot find via reads and searches. See Discoverable vs Non-Discoverable Context.

3. Mechanical enforcement of taste

Encode conventions as lint rules and CI checks. Agents respond to pass/fail signals, not rationale (Wadia, Sng).

When This Backfires

Knowledge externalization adds overhead proportional to churn. Conditions where the cure is worse than the disease:

  • Rapidly-changing conventions — in early-stage projects where naming, structure, and patterns shift weekly, an AGENTS.md capturing yesterday's convention actively misleads agents. Stale documentation causes more silent errors than no documentation.
  • One-person projects — the problem is social: conventions exist only in one mind because there is no institutional memory to externalize. An instruction file in a solo codebase adds write cost with minimal agent benefit; discoverable context in the code structure does more.
  • The convention is already discoverable — agents read code. Naming patterns evident from 50+ files don't need an AGENTS.md entry; adding them creates redundancy with no enforcement benefit.
  • Overly large instruction files — monolithic AGENTS.md that capture everything become noisy enough that agents hallucinate compliance. Keep files thin and point to reference directories; prefer mechanical enforcement over documentation for stable rules.

Example

A team's convention is that HTTP handler files use a -handler suffix. The convention exists only as tribal knowledge.

Without externalized knowledge -- the agent infers from the one file it happens to see:

# Agent creates a new endpoint
src/
  orders-service.ts    # ← wrong suffix, matches nothing in the codebase

The file compiles, tests pass, and the naming violation ships undetected.

With externalized knowledge -- an AGENTS.md entry and a lint rule make the convention discoverable and enforceable:

# AGENTS.md
- HTTP handler files must use the `-handler.ts` suffix (e.g., `orders-handler.ts`).

// eslint rule: enforce-handler-suffix
// Fails CI if a file in src/ uses `-service.ts` instead of `-handler.ts`

The agent reads the convention from AGENTS.md, and even if it guesses wrong, the lint rule catches the mistake before commit.

Established — multiple independent sources Last reviewed: 2026-06-12
Feedback