LLM Wiki

Appearance

Built 26/04/17 09:08commit f8ff6f9

Agent-First Repositories ​

中文 | English

Summary ​

An agent-first repository is organized so models can reason about the product, architecture, quality bar, and operational state directly from versioned local artifacts, without depending on hidden human context.

Core Principles ​

  • Humans steer intent and priorities; agents execute most implementation and maintenance work.
  • Repository-local artifacts are the system of record because anything outside the repo is effectively invisible to an agent run.
  • AGENTS.md should be a compact map into deeper documentation, not a monolithic instruction dump.
  • Progressive disclosure beats encyclopedic guidance: start with stable entry points, then teach the agent where to drill deeper.

Legibility Levers ​

  • Make the UI legible through browser automation, screenshots, DOM state, and repeatable app startup flows.
  • Make frontend taste legible through repo-local design contracts such as DESIGN.md, so agents can anchor visual decisions in durable rules rather than chat-only guidance.
  • Make runtime behavior legible through logs, metrics, traces, and other queryable observability surfaces.
  • Make architecture legible through fixed layer boundaries, domain maps, mechanical checks on dependency direction, and regenerable diagram artifacts that keep system structure readable from repo-local text.
  • Make loop state legible through small durable files such as specs, PRDs, fix plans, and progress logs that every fresh-context run can reload quickly.
  • Make review and delivery legible by preserving plans, review comments, quality grades, and remediation patterns in-repo.

Control Systems ​

  • Encode important invariants in linters, structural tests, and error messages that tell agents how to recover.
  • Capture human taste once as documentation or tooling, then enforce it continuously rather than repeatedly re-explaining it.
  • Keep durable operating defaults in config.toml and durable repo rules in AGENTS.md; prompts should carry task-local deltas, not the whole operating manual.
  • Reusable command bundles matter because they turn fuzzy methodology into inspectable repository surfaces: ideation, planning, review, and knowledge capture can ship as named commands instead of oral tradition.
  • Reusable agent operating models can themselves be packaged as repo assets such as skills, plugin manifests, and bootstrap scripts, making the control surface portable across projects.
  • Mature agent repos often expose the same operating model through multiple harness-native surfaces at once, for example Claude plugins, Codex config and roles, Cursor/Kiro/OpenCode trees, and installer scripts that keep them aligned.
  • Team-ready agent repos also need a distribution story: global installs, project bootstrap commands, environment checks, upgrade paths, and runtime registration flows are increasingly part of the repo contract.
  • Cross-runtime bridge plugins are another emerging repo surface: they package one agent system as native commands inside another, so review lanes, delegated work, and verification gates become installable repo-level assets instead of ad hoc shell choreography.
  • Some repos go further and present one agent environment as a virtual engineering office with named review perspectives, so product, design, QA, security, and release work become explicit repository-native lanes rather than chat-only reminders.
  • Compact methodology packs can travel as plugin metadata, project instruction files, and reusable skills at the same time, turning one operator insight into a portable repository asset.
  • Some agent-first systems also push beyond repo-local control and treat issue boards, daemon-attached runtimes, and assignable agent identities as part of the operational surface.
  • Prompt-inventory repositories are another emerging legibility layer: they turn otherwise hidden built-in prompts, tool descriptions, safety monitors, and utility routines into versioned assets that operators can inspect and diff.
  • Use recurring cleanup work as garbage collection so bad patterns are corrected before they spread.

Tradeoffs ​

  • Strict boundaries and explicit scaffolding increase agent throughput, but require ongoing maintenance of the repository's guidance surfaces.
  • High throughput changes merge philosophy: short PRs and cheap follow-up fixes can be preferable to long human-blocked review queues.
  • Full autonomy raises new long-term questions around entropy, architectural drift, and where human judgment adds the most leverage.

Sources ​