Agent Context Files (CLAUDE.md / AGENTS.md)

Project-level markdown files read by coding agents at session start that carry persistent context: architecture, conventions, constraints, and team intent.

Also known as: CLAUDE.md, claude.md, AGENTS.md, agents.md, AGENT.md / INFO.md, AGENT.md, AGENTS.md (as intent ledger, not config), context files, folder = agent, workspace, Cursor rules, program MD

Part of: Agent Harness

How authors use it

Oldest first (extraction date when no publication date is known).

Documents (27)

• Agent-First Engineering: 9 Playbook Tips for a Zero-Human-Code Future Avi Pilcer · 2026-10-08 Reader 🖥️
  A codebase and its surrounding processes must be deliberately re-engineered — minimal, pointer-style instruction files, plans and architecture decisions checked in as versioned markdown, boring/predictable tooling, and scheduled background agents for cleanup and doc-sync — to remain legible and non-degrading as the volume of agent-written code grows toward (the author claims) zero human-written code; the engineer's job shifts from writing code to designing this environment.
• Zero to Agent in 30 Minutes: Build a Sports Concierge Agent with Chester Ismay Michelle Smith · 2026-09-21 Reader 🖥️
  A minimal-infrastructure pattern — a single markdown policy file plus pre-fetched data, scoped tool permissions, and ordinary OS scheduling — is enough to turn a recurring personal decision into a reliable, unattended weekly agent, without needing dedicated agent-orchestration infrastructure.
• Audit your Agent files AddyOsmani.com · 2026-08-27 source ↗ Reader 🖥️
  Coding-agent configuration (CLAUDE.md/AGENTS.md, skills, hooks, MCP servers, memory) has a half-life because models and harnesses keep improving past what the rules were written for, so instead of accumulating it indefinitely or purging it wholesale, developers should audit it on a recurring cadence — using tools like /doctor, questioning whether each item's original reason still holds, and testing removal before committing to it.
• Paweł Huryn's Post Paweł Huryn · 2026-08-01 Reader 🖥️
  For most AI agents, the four functional types of memory — working, semantic, episodic, and procedural — map cleanly onto a context window plus a handful of git-versioned files (markdown for facts/rules, a CSV for history, more markdown for reusable skills), making vector databases and graph databases unnecessary defaults, appropriate only as 'escape hatches' when a corpus genuinely becomes too large to read.
• The Orchestrator's Tax Rahul Garg (martinfowler.com; edited/guided by Martin Fowler) · 2026-07-28 source ↗ Reader 🖥️
  The real value of a subagent is not the wall-clock time it saves through parallel execution but what it keeps out of the orchestrator's context, so multi-agent workflows should be designed and governed around protecting the orchestrator's limited working memory — via task splits that respect 'cognitive locality' and via minimal, fact-justified standing rules — rather than around maximizing delegation, agent count, or governance.
• My AI Kept Pushing Me to Ship, So I Asked It Why Andrew Stellman · 2026-07-21 source ↗ Reader 🖥️
  Agentic coding models exhibit a structural default the author names continuation pressure — every turn is built as a handoff that leaves a next action queued rather than genuinely finishing — which surfaces as deferral and velocity pressure, resists naming and phrase-banning because it simply relocates to unconstrained vocabulary, and can only be suppressed (not eliminated) by a structural rule that makes an explicit 'done, nothing queued' resting state a legitimate way to end a turn.
• The boring skill that decides how much AI can help you Ernie Svenson · 2026-07-14 source ↗ Reader 🖥️
  Because agentic AI now acts directly on your files rather than only answering chat questions, it amplifies whatever organizational structure already exists there — so basic, personally-fitted file-organization discipline, not technical sophistication, is the decisive skill that determines how much leverage you get from AI.
• Your AGENTS.md might be a big problem Matt Pocock (AI Hero) · 2026-07-03 Reader 🖥️
  A reactively bloated AGENTS.md degrades an AI coding agent because it spends the model's finite instruction-following budget on every request, so you should keep the root file to 3-5 essentials and push everything else into nested files the agent loads only when relevant.
• The Claude Code active attack didn't stop. 294,842 secrets stolen from 6,943 machines. It evolved and now spreads through Python too and uses Claude Code itself to steal your secrets. The risk to your credentials just got bigger. johnypita · 2026-06-10 source ↗ Reader 🖥️
  A months-long, commoditised software supply-chain campaign aimed at developer credentials has evolved to target the AI layer itself — fooling AI malware reviewers and planting persistent instructions in coding-agent configuration so the developer's own agent acts with the access already granted to it — which means credential exposure, not malware, is the real risk and cleanup must neutralise agent-config persistence before credentials are rotated.
• The Intent Debt Addy Osmani (addyosmani.com) · 2026-06-06 Reader 🖥️
  Intent debt — the absence of externalized rationale, goals and constraints in artifacts an agent can actually read — is the one of Storey's three debts (technical, cognitive, intent) that AI agents structurally cannot pay down, because intent is the one input that must originate with a human; and because agents start every session cold with no tacit memory, every gap in the externalized why is now paid every session by every agent, making the previously-affordable habit of carrying intent in your head the single most expensive workflow choice in agent-assisted development.
• A harness for every task: dynamic workflows in Claude Code Thariq Shihipar and Sid Bidasaria (Anthropic, Claude Code team) · 2026-06-02 source ↗ Reader 🖥️
  Because a single, continuously-running context window degrades on long, parallel, structured, or adversarial tasks through three specific failure modes — agentic laziness, self-preferential bias, and goal drift — Claude Code should let the model write and orchestrate a custom, task-specific multi-agent harness (a dynamic workflow) on the fly, rather than relying on one generic static harness for every task.
• JobRunr Introduces ClawRunr, an Open-Source Java AI Agent Diogo Carleto · 2026-05-18 Reader 🖥️
  ClawRunr is JobRunr's open-source Java AI agent that wraps Spring AI's ChatClient with JobRunr's durable, retryable, scheduled job execution, packaging conversational LLM interaction with first-class persistence, recurrence, and monitoring so that long-running agent work behaves like production background jobs rather than ephemeral chat completions.
• How Claude Code works in large codebases: Best practices and where to start Claude · 2026-05-14 source ↗ Reader 🖥️
  At scale — multi-million-line monorepos, decades-old legacy systems, and organizations with thousands of developers — Claude Code's effectiveness is determined less by the underlying model than by a deliberately built harness (CLAUDE.md, hooks, skills, plugins, MCP servers, plus LSP integrations and subagents) and, just as importantly, by a durable organizational ownership structure (a dedicated owner or team, cross-functional governance, scheduled re-review as models evolve) that keeps good setups from staying tribal and adoption from plateauing.
• This week on How I AI: The internal AI tool that's transforming how Stripe designs products (Protodash at Stripe) Lenny's Newsletter / Owen Williams · 2026-05-09 Reader 🖥️
  Internal AI prototyping tools that embed a company's own design system produce dramatically higher-fidelity results than generic AI tools, and when made accessible to non-engineers (designers, PMs), they shift organizational culture from document-based proposals to working demos — enabling faster exploration, better cross-functional communication, and more-informed design decisions.
• The Founder's Playbook: Building An AI-Native Startup Claude (Anthropic) · 2026-05-05 source ↗ Reader 🖥️
  Because AI now collapses the cost of building, researching, and operating a company, the AI-native founder's job is no longer execution but orchestration of AI across four stages (Idea, MVP, Launch, Scale), and a small (often single-founder) team that systematically routes work through Claude, Claude Cowork, and Claude Code can reach outcomes that previously required a fully-staffed organisation.
• Agent Harness Engineering Addy Osmani · 2026-04-20 source ↗ Reader 🖥️
  The performance gap between what current AI models can do and what users actually experience is primarily a harness-engineering gap — the scaffolding of prompts, tools, hooks, context management, and feedback loops wrapped around the model — and closing it requires treating that scaffolding as a continuously evolving engineering artifact shaped by observed failures.
• Jacob Langvad Nilsson's Post Jacob Langvad Nilsson · 2026-04-20 source ↗ Reader 🖥️
  Effective use of AI coding agents depends not on better prompting but on providing structured context — plans, specs, skills, hooks, and a clear understanding of the agentic loop — which is the real unlock for productive human-AI collaboration in software development.
• Alex Wang's Post Alex Wang · 2026-04-16 Reader 🖥️
  Claude Code becomes more reliable when you move recurring, deterministic, and structural concerns out of ad-hoc prompts and into the environment (CLAUDE.md, skills, hooks, plan mode).
• Charlie Hills 🦩's Post Charlie Hills 🦩 · 2026-04-16 source ↗ Reader 🖥️
  Effective use of Claude Code requires deliberate setup, disciplined workflow habits, context management, precise prompting, and exploitation of power features — and learning these on day one would save weeks of friction.
• Anatomy of a perfect Openclaw setup Corey Ganim · 2026-04-10 Reader 🖥️
  A well-configured OpenClaw workspace — organized around a set of markdown files (AGENTS.md, SOUL.md, IDENTITY.md, USER.md, HEARTBEAT.md, TOOLS.md) plus skills, memory, and secrets folders — is the key to making an AI assistant behave reliably and proactively, with AGENTS.md as the single highest-leverage file.
• Encoding Team Standards Rahul Garg · 2026-03-31 source ↗ Reader 🖥️
  A team's standards for how AI should generate, refactor, secure, and review code must stop living as tacit judgment in senior engineers' heads or as unread documentation, and instead be encoded as small, versioned, repository-resident AI instructions — because an instruction's execution is its application, which turns consistent team judgment into a side effect of the normal workflow rather than a separate step that depends on someone remembering and applying it under pressure.
• Skill Issue: Andrej Karpathy on Code Agents, AutoResearch, and the Loopy Era of AI No Priors: AI, Machine Learning, Tech, & Startups · 2026-03-20 Reader 🖥️
  The jump in code-agent capability since December 2024 has made human throughput — not model capability — the binding constraint, and the central challenge is now removing yourself from the loop so autonomous agents can maximize token throughput on your behalf.
• Stop Using /init for AGENTS.md Addy Osmani · 2026-02-23 source ↗ Reader 🖥️
  AGENTS.md should hold only project-specific facts an agent cannot discover by reading the code itself — because auto-generated, comprehensiveness-optimized context files duplicate what agents already find on their own and measurably slow and bias them — and the file should function as a living log of unfixed codebase friction to be resolved in the code, not as a permanent, ever-growing configuration.
• Harness engineering: leveraging Codex in an agent-first world Ryan Lopopolo (OpenAI) · 2026-02-11 source ↗ Reader 🖥️
  Building a product with zero manually-written code at scale (one million-plus lines, five months, a team that grew from three to seven engineers with throughput that increased rather than degraded) required redefining engineering work from writing code to designing environments, pushing all team knowledge into repository-local legible artifacts, mechanically enforcing architectural invariants and documentation freshness, and relaxing human-paced process norms (blocking merge gates, manual cleanup) in favor of continuous, agent-driven correction — because human time and attention, not code production, is the one truly scarce resource the whole system must be organized to protect.
• Just Talk To It - the no-bs Way of Agentic Engineering Peter Steinberger · 2025-10-14 source ↗ Reader 🖥️
  As coding-agent models (specifically GPT-5-Codex) get good enough to read a codebase and follow short, direct instructions on their own, most agentic-engineering 'harness ceremony' — subagents, RAG, elaborate plan files, custom hooks, MCP servers — becomes charade that works around older model limitations rather than exploiting current model capability, so the highest-leverage practice for a solo developer is to talk to the model directly and let judgment (about blast radius, context budget, and when real structure is needed) develop through intuition rather than process.
• How Anthropic Teams Use Claude Code Anthropic · 2025-06-03 Reader 🖥️
  Across nine internal teams spanning both engineering (Security, Inference, RL Engineering, the Claude Code team itself) and non-engineering functions (Legal, Growth Marketing, Product Design, Finance via Data Infrastructure), Claude Code's value comes less from writing application code per se than from acting as a general-purpose interface to unfamiliar systems, documentation, and workflows -- letting people without coding backgrounds independently build and run working software, and letting engineers extend their reach into unfamiliar domains -- provided teams invest in persistent context files, checkpoint-heavy supervision, and an explicit sense of which tasks warrant autonomous versus closely-supervised execution.
• Claude Code: Best practices for agentic coding anthropic.com · 2025-04-18 source ↗ Reader 🖥️
  Because Claude Code is deliberately low-level and unopinionated, its effectiveness on your problem is set by the harness you engineer around the model — the context, tools, and workflow you supply — not by the raw model alone.

Propositions touching this concept (62)

By publication month, oldest first (extraction month when no publication date is known).

2025-01

• explicit⚡ disputed & corroboratedAdding more context (context files, ADRs, rules) to guide agent behavior degrades output quality rather than improving it, because summarization quality degrades as context grows.
  Agents don't know what good looks like. And that's exactly the problem. · p4

2025-04

• explicitA CLAUDE.md file, automatically pulled into context when a conversation starts, is the primary place to give Claude persistent project context: common commands, core files, code style, testing instructions, repo etiquette, environment setup, and project-specific warnings.
  Claude Code: Best practices for agentic coding · p2
• explicitCLAUDE.md files should be treated and refined like any frequently used prompt — kept concise and iterated on (via the prompt improver and emphasis such as IMPORTANT/YOU MUST) — because adding extensive content without iterating on its effectiveness is a common mistake that hurts instruction-following.
  Claude Code: Best practices for agentic coding · p3
• implicitThe model's effective performance on your codebase is bounded by the harness you assemble around it — CLAUDE.md context, the curated tool allow-list, MCP servers, and custom bash scripts and slash commands — not by the raw model weights alone, so configuring that context-and-tool layer is the user's highest-leverage action.
  Claude Code: Best practices for agentic coding · p4
• implicitThe directory placement of CLAUDE.md is itself a context-budgeting mechanism: files in parent directories are pulled into context automatically at session start, while files in child directories are pulled in only on demand when Claude works with those subtrees, scoping instructions to where they are relevant.
  Claude Code: Best practices for agentic coding · p17
• explicitcontestedYou should use the # key to have Claude append new instructions to the relevant CLAUDE.md as you work, and commit those changes so teammates benefit — steadily accreting project knowledge into the file over time.
  Claude Code: Best practices for agentic coding · p18

2025-06

• explicitWriting and maintaining project-level context files (Claude.md) that document workflows, tools, conventions, and even the user's own skill level (e.g. 'I'm a designer with little coding experience, give detailed explanations and smaller changes') measurably improves the quality and reliability of Claude Code's output, and multiple teams describe this as the single highest-leverage investment for ongoing use.
  How Anthropic Teams Use Claude Code · p5

2025-10

• explicitcontestedHis ~800-line AGENTS.md (symlinked as CLAUDE.md) file is 'a collection of organizational scar tissue' that he never hand-writes — the agent appends its own notes after incidents — and he expects it to keep shrinking as models absorb more world knowledge (he deleted all his Tailwind-4 guidance once newer models already knew the framework).
  Just Talk To It - the no-bs Way of Agentic Engineering · p7

2026-01

• explicitA team-wide CLAUDE.md instructional file (e.g. 'always run via this command,' 'always lint before a PR') and giving the agent a way to verify its own work are, in Boris Cherny's account, the most important levers for getting high-quality results — he states that a working verification feedback loop alone can 2-3x result quality.
  The Pulse #158: New Ways Of Coding With AI Tools · p7

2026-02

• explicitA single large 'AGENTS.md' instruction file fails in four specific, predictable ways at scale — it crowds out task/code/doc context, makes all guidance equally unprioritized ('too much guidance becomes non-guidance'), rots because no one maintains a monolithic file, and resists mechanical verification (coverage, freshness, ownership, cross-links) — so AGENTS.md should function as a short table-of-contents pointing into a structured docs/ directory that is the actual system of record.
  Harness engineering: leveraging Codex in an agent-first world · p5
• explicitA paired experiment on 124 real GitHub PRs (Lulla et al., ICSE JAWs 2026) found that the presence of an AGENTS.md file reduced median wall-clock runtime by 28.64% and output token consumption by 16.58%, holding task, repo, and agent constant.
  Stop Using /init for AGENTS.md · p1
• explicitA separate ETH Zurich study found that LLM-generated (auto-generated) context files reduced task success by 2-3% while increasing cost by over 20%, whereas developer-written files improved success by about 4% while increasing cost by up to 19%.
  Stop Using /init for AGENTS.md · p2
• explicitMerely stating a fact in AGENTS.md (e.g. a legacy tech-stack detail) biases the agent toward that pattern on every future prompt, because the model does not distinguish 'this is what we used to do' from 'this is what you should do' — an anchoring cost independent of the fact's accuracy.
  Stop Using /init for AGENTS.md · p4
• explicitThe ETH Zurich paper found that /init-style auto-generation is overwhelmingly codebase-overview content: 100% of Sonnet 4.5's and 99% of GPT-5.2's auto-generated context files contained codebase overviews — exactly the content an agent discovers anyway by listing directories and reading READMEs.
  Stop Using /init for AGENTS.md · p5
• explicitThe right inclusion test for an AGENTS.md line is whether it is non-discoverable from the codebase, operationally significant, and impossible to guess by convention (e.g. 'use uv, not pip' — which raised per-task tool usage from under 0.01 to 1.6 when stated) — not whether it is true or helpful to a human reader.
  Stop Using /init for AGENTS.md · p6
• explicitAutomated prompt-optimization of CLAUDE.md instructions (Arize AI's generator/evaluate/feedback/meta-prompt loop) outperformed manually written instructions by +5.19% accuracy cross-repo and +10.87% in-repo, because what a human finds obviously useful and what actually helps the model navigate a codebase are often different things.
  Stop Using /init for AGENTS.md · p10
• explicitAGENTS.md should function as a diagnostic log of unfixed codebase friction: an agent's repeated mistake should first be investigated as a codebase problem (confusing directory structure, an easy-to-grab deprecated dependency, a missing automated check) and fixed in the code or build pipeline; only if that's not possible should the fix remain as a prose instruction, which should then be deletable once the underlying problem is addressed.
  Stop Using /init for AGENTS.md · p11
• explicitInstructions essential to a context file today lose value over a few months as underlying models improve at codebase navigation on their own, so a well-tuned AGENTS.md can become net overhead by the next quarter purely from model improvement, independent of codebase or content changes.
  Stop Using /init for AGENTS.md · p12

2026-04

• explicitcorroboratedEvery line in a good AGENTS.md should be traceable back to a specific thing that went wrong.
  Agent Harness Engineering · p4
• explicitPush (CLAUDE.md) and pull (skills) serve different roles: implementers should pull coding standards (so they aren't drowned in irrelevant rules); reviewers should be pushed coding standards (so they always compare).
  [FULL WORKSHOP] AI Coding For Real Engineers - Matt Pocock, AI Hero · p12
• explicitcontestedCLAUDE.md should contain stable project context (architecture, conventions, commands), not procedural playbooks.
  Alex Wang's Post · p1
• explicitestablishedRepeatable procedures, checklists, and playbooks belong in a separate mechanism (skills), not in CLAUDE.md.
  Alex Wang's Post · p2
• explicitAGENTS.md is the single highest-leverage file in an OpenClaw setup; getting it right matters more than everything else.
  Anatomy of a perfect Openclaw setup · p1
• explicitcorroboratedAGENTS.md should be kept under 300 lines because longer files consume too much context and reduce instruction adherence.
  Anatomy of a perfect Openclaw setup · p2
• explicitMost users fail to configure their workspace at all, which is a mistake because the workspace is the control center for agent behavior.
  Anatomy of a perfect Openclaw setup · p3
• implicitSeparating configuration into multiple specialized files (AGENTS.md, SOUL.md, IDENTITY.md, USER.md, etc.) is better than a monolithic config because each file serves a different purpose and changes at a different rate.
  Anatomy of a perfect Openclaw setup · p4
• explicitA 6-step progressive setup (onboard, AGENTS.md, identity files, first skill, memory, TOOLS.md) covers 95% of use cases.
  Anatomy of a perfect Openclaw setup · p6
• explicitcorroboratedCLAUDE.md sets persistent rules that apply across every Claude Code session in a project.
  Charlie Hills 🦩's Post · p1
• explicitdevelopedAn AI agent can be created simply by defining a folder with a CLAUDE.md file — no deployment infrastructure needed.
  Jacob Langvad Nilsson's Post · p8
• explicitContext files (CLAUDE.md, AGENTS.md) accumulate rules over time into 'agent instruction bloat': instructions grow long, start conflicting, and models attend less to content buried mid-context, so adding more rules can make an agent less reliable, not more — and hand-written instruction files tend to outperform LLM-generated ones.
  Technology Radar, Volume 34 · p12
• explicitTreating curated, shared AI instructions (CLAUDE.md/AGENTS.md anchored into service templates, or a live reference application as source of truth) as a collaborative team engineering asset — rather than something each developer writes ad hoc — is now the more mature practice than individual prompt libraries.
  Technology Radar, Volume 34 · p16

2026-05

• explicitThe harness has an intentional build order across five extension points — CLAUDE.md, hooks, skills, plugins, MCP servers — each layer building on what came before, plus two further capabilities (LSP integrations, subagents) that round out the setup.
  How Claude Code works in large codebases: Best practices and where to start · p3
• explicitcorroboratedHooks' most valuable use is not preventing mistakes but making the setup self-improving — e.g. a stop hook that reflects on a session and proposes CLAUDE.md updates while context is fresh, or a start hook that dynamically loads the right team-specific context per module without manual configuration.
  How Claude Code works in large codebases: Best practices and where to start · p4
• explicitAs models evolve, CLAUDE.md instructions and compensatory skills/hooks written for a weaker model's limitations can become unnecessary or actively counterproductive for a newer model — e.g. a rule forcing single-file refactors that blocks a newer model's legitimate coordinated cross-file edits — so teams should expect a meaningful configuration review every three to six months, and especially after major model releases.
  How Claude Code works in large codebases: Best practices and where to start · p8
• explicitA new, hybrid PM/engineer role — 'agent manager' — is emerging in several organizations specifically to own the Claude Code ecosystem; organizations without a dedicated team should at minimum designate a DRI with explicit authority over settings, permissions policy, the plugin marketplace, and CLAUDE.md conventions.
  How Claude Code works in large codebases: Best practices and where to start · p10
• explicitPer-repo documentation approaches like AGENTS.md do not scale to an organization with hundreds or thousands of repos, because there is no mechanism to keep them synchronized or applied consistently across teams.
  Why AI agents need a Context Lake · p3
• explicitArchitectural decisions must be written down (in a CLAUDE.md or equivalent) before agentic coding begins, or the codebase will silently become structurally incoherent and eventually need a rewrite.
  The Founder's Playbook: Building An AI-Native Startup · p6
• design claimcorroboratedComposing the system prompt from workspace files (AGENT.md, INFO.md) makes agent behavior configurable without code changes.
  JobRunr Introduces ClawRunr, an Open-Source Java AI Agent · p4
• extensibility claimFile-based skills loaded from a workspace directory enable runtime extensibility without redeployment.
  JobRunr Introduces ClawRunr, an Open-Source Java AI Agent · p7
• explicitdevelopedEmbedding a company's design system into AI tooling (via MCP, Cursor rules, bundled components) produces dramatically higher-fidelity prototypes.
  This week on How I AI: The internal AI tool that's transforming how Stripe designs products (Protodash at Stripe) · p2

2026-06

• explicitA team's recurring corrections (from session histories or code-review comments) can be mined by parallel agents, adversarially verified ('would this rule have prevented a real mistake?'), and distilled into CLAUDE.md rules — and the reverse workflow (checking existing CLAUDE.md rules against a skeptic-persona subagent) is equally viable.
  A harness for every task: dynamic workflows in Claude Code · p7
• explicitAgent context and configuration files (CLAUDE.md, rules files, settings) are fed into every session, so anyone who can write to them controls all future agent interactions without touching the code; teams should audit and protect them like SSH config or CI secrets — a real attack surface most teams are not watching.
  The Claude Code active attack didn't stop. 294,842 secrets stolen from 6,943 machines. It evolved and now spreads through Python too and uses Claude Code itself to steal your secrets. The risk to your credentials just got bigger. · p16
• implicitA team's incentive structure must actually reward the upfront CapEx investment (writing tests/evals before code, maintaining AGENTS.md as reviewed code, owning harness components as shared infrastructure) for agentic engineering's economics to pay off — otherwise the easier, cheaper-looking vibe-coding path wins by default under normal shipping-speed pressure.
  The New SDLC With Vibe Coding: From ad-hoc prompting to Agentic Engineering · p17
• explicitcorroboratedAGENTS.md should be treated as an intent ledger (conventions, 'we don't do it this way because…') not as auto-generated config describing what the code is.
  The Intent Debt · p18
• implicitestablishedAGENTS.md, ADRs, learnings files and specs are the right substrate for externalized intent — i.e., the right artifact format already exists.
  The Intent Debt · p25

2026-07

• explicitThe agent cannot infer whether a repo is a throwaway prototype, production code, or a public library — each carries a different quality bar — so the human must state the intended quality level explicitly (in AGENTS.md, skills, or the prompt) or the agent will guess wrong.
  11 Tips For AI Coding With Ralph Wiggum · p10
• explicitdevelopedA bloated AGENTS.md degrades coding-agent performance rather than improving it.
  Your AGENTS.md might be a big problem · p1
• explicit⚡ disputed & corroboratedAGENTS.md bloat forms reactively and invisibly — developers append a rule after each agent failure until the file sprawls.
  Your AGENTS.md might be a big problem · p2
• explicitcorroboratedEvery rule in AGENTS.md consumes instruction budget on every request, whether or not it is relevant to that request.
  Your AGENTS.md might be a big problem · p4
• implicitThe root AGENTS.md is loaded wholesale into the model's context on every request, which is why irrelevant rules still cost budget.
  Your AGENTS.md might be a big problem · p5
• explicitCode review should run as independent concerns in parallel: a standards axis (does the code conform to the repo's documented coding standards) and a spec axis (does the code faithfully implement the originating spec/issue), each a separate sub-agent — and coding standards belong in a separate coding-standards file, kept out of the always-loaded AGENTS.md and pulled in at review time, where they are most useful.
  New Skills! v1.1 brings /wayfinder, /research, /implement, /to-spec, /to-tickets · p6
• explicitThe core reasoning loop of a functioning coding or search agent can be implemented in roughly 60-130 lines of Python, showing the underlying agentic-loop pattern stays small even as the surrounding harness that builders actively extend (AGENTS.md instructions, skills, evals) grows large.
  Stop Overengineering Your Agent Harness · p5

2026-08

• explicitestablishedAGENTS.md/CLAUDE.md bloat forms through a self-reinforcing four-step cycle: the agent errs once in a way that stings, a rule is added (reasonable in isolation), the file grows and dilutes what matters, and adherence drops, producing more errors and more rules.
  Audit your Agent files · p2
• explicit⚡ disputed & corroboratedAcross 288 runs on 17 real tasks, context files (AGENTS.md/CLAUDE.md) did not produce a clear gain in Claude Code/Codex task correctness, though they did change how the agents worked (e.g. running more targeted tests when warned a suite was slow).
  Audit your Agent files · p4
• explicitProse summaries of code answer far fewer behavioral questions than the source code itself (4 of 45 vs. 27 of 45), because summaries smooth over the small details that matter — so context files should point agents at real code rather than describe it.
  Audit your Agent files · p6
• explicit⚡ disputed & corroboratedInstitutional knowledge that used to sit in people's heads and on wikis becomes version-controlled, team-shared files — CLAUDE.md and skills — that every agent session reads at the start, maintained by the whole team and reviewed like code rather than owned by any one person's memory.
  The AI-Native SDLC playbook · p7
• explicitAs guardrails mature (a tuned CLAUDE.md, policy-encoding skills, blocking hooks, a test suite Claude can run), auto-accept becomes the default for routine work, and human review shifts from watching each edit as it happens to reviewing artifacts after longer autonomous sessions.
  The AI-Native SDLC playbook · p10
• explicitContinuous evals function as the regression-test suite for the agent's own configuration: they must re-run whenever CLAUDE.md, a skill, or a hook changes, because a model swap or prompt rewrite can silently change behavior that was previously verified by hand only once.
  The AI-Native SDLC playbook · p17

2026-09

• explicitInstructions given to an AI coding agent through text (context files, style guides, pasted wikis) function as suggestions rather than enforced rules; what the repository technically permits is what actually happens.
  From AI Code to Trusted Software: Harness Engineering in Practice · p1
• explicitAn earlier, advisory version of the routing logic — a block of rules in CLAUDE.md instructing Claude to self-route to Portal — worked only partially: Claude could ignore the rules, and every project needed its own copy of them.
  Portal by Spotify cut my Claude Code token usage by 90% · p5
• explicitDevelopers convert recurring supervisory corrections into persistent, reusable assets (linters, MISTAKES.md-style logs, CLAUDE.md-style instruction files, retrospective-generated skill files) specifically to prevent repeating the same correction in future tasks, producing what developers describe as a compounding reduction in supervisory burden across a project's lifetime.
  The Work Behind Delegation: A Framework for Supervising AI Coding Agents · p7

2026-10

• explicitCoding-agent instruction files (CLAUDE.md/AGENTS.md) should be minimal (~100 lines), pointer-based tables of contents rather than exhaustive manuals, because treating everything as important dilutes what the agent actually attends to.
  Agent-First Engineering: 9 Playbook Tips for a Zero-Human-Code Future · p1

Tensions

Open gaps (63)

• incompleteThe Terminal Bench 2.0 data point (Top 30 to Top 5 via harness change) is presented without detail on what specific harness changes drove the improvement, making it impossible to evaluate which components had the most leverage.
  Agent Harness Engineering — read next: Read Viv Trivedy's original 'Anatomy of an Agent Harness' post for the detailed breakdown.
• incompleteThe 'self-improvement loop' is described as agents saving learnings back to context files, but there is no discussion of knowledge curation — who reviews what the agents learn? Unbounded accumulation of agent-generated context could itself become a source of context rot.
  Accelerating Delivery: How AI Agents Can Own the Initial Code Draft — read next: Knowledge management literature on automated knowledge bases; the 'wiki decay' problem applied to agent memory
• incompleteNo evidence or examples are provided for any of the four habits. The claims are presented as practitioner wisdom without empirical support, before-after comparisons, or concrete scenarios showing failure modes.
  Alex Wang's Post
• incompleteThe distinction between what belongs in CLAUDE.md vs. skills vs. hooks is stated but not precisely bounded. A convention that is also a checklist could plausibly go in either place.
  Alex Wang's Post
• uninformedThe post does not address trade-offs or costs of the recommended approach -- e.g., the overhead of maintaining skills and hooks, the risk of over-engineering small projects, or when ad-hoc prompting is actually sufficient.
  Alex Wang's Post
• incompleteThe post ends with a course promotion, raising the question of whether the advice is calibrated to be genuinely complete or deliberately leaves gaps to motivate enrolment.
  Alex Wang's Post
• omissionNo discussion of version control for workspace files, collaboration between multiple users, or backup strategies.
  Anatomy of a perfect Openclaw setup — read next: Best practices for managing AI agent configurations in team settings.
• omissionNo mention of cost implications — longer AGENTS.md means more tokens per session, which affects API costs.
  Anatomy of a perfect Openclaw setup — read next: Token economics of system prompt design.
• commercialThe post is partly a lead-generation piece for the author's 'Build With AI' community, which may bias toward presenting OpenClaw as more powerful/important than alternatives.
  Anatomy of a perfect Openclaw setup — read next: Compare with other AI assistant frameworks (e.g., Claude Code's CLAUDE.md, Cursor rules, etc.).
• uninformedThe cited personalization study used an LLM-based developer simulator rather than real developers (a caveat the author names), and the context-file study covers a specific harness/model pairing (Claude Code and Codex). The article doesn't discuss whether either finding would transfer to other harnesses, to less tool-augmented agents, or to real (non-simulated) developer populations, despite building a general prescription on top of both.
  Audit your Agent files — read next: Follow-up studies replicating the personalization and context-file findings with real developer cohorts and across multiple harnesses, to test whether the 'generic beats personal' and 'context files don't move correctness' results are harness-specific artifacts or general findings.
• incompleteNo evidence or reasoning is provided for any of the 32 claims. Every tip is stated as flat assertion. There is no explanation of WHY each practice works, what failure mode it prevents, or how the author discovered it. This makes it impossible to evaluate which tips generalize vs. which are idiosyncratic to the author's workflow.
  Charlie Hills 🦩's Post — read next: Look for experience reports or controlled comparisons of Claude Code workflows (e.g., with vs. without CLAUDE.md, with vs. without branching per task).
• incompleteThe social media format (LinkedIn listicle) constrains depth. Tips like 'Set a scope limit to only the files you name' and 'Replan at halfway to reset the goal' are operationally vague — a reader new to Claude Code would not know how to implement them.
  Charlie Hills 🦩's Post — read next: The author's own linked guides (beginner-to-advanced, design-in-code) likely expand on these compressed tips.
• generalizabilityAll data comes from a single team's workflow (systems programming, MLIR, GPU drivers) with a specific CLAUDE.md configuration. It is unclear whether the regression equally affects other domains or simpler tasks.
  [MODEL] Claude Code is unusable for complex engineering tasks with the Feb updates #42796 — read next: Cross-reference with other issue reports in the claude-code repository to see if the pattern is domain-specific or universal.
• incompleteThe 'actively maintaining CLAUDE.md' section recommends scheduled review and pruning but doesn't address the risk that removing an old compensatory rule or hook could regress behavior in an edge case the newer model still doesn't fully handle — the article's framing of review-and-prune reads more confidently certain than the underlying risk (removing a safeguard without being sure it's actually obsolete) would warrant.
  How Claude Code works in large codebases: Best practices and where to start — read next: Look for guidance or tooling on testing/validating that a removed CLAUDE.md rule or hook is genuinely redundant before deleting it, rather than relying on developer judgment alone.
• incompleteThe post summarizes slide decks (149 pages) that are only available as images. The textual content is a curator's frame, not the primary source material. Key details, evidence, and nuance from the actual presentations are inaccessible.
  Jacob Langvad Nilsson's Post — read next: Access the original slide decks or video recordings if available to extract the full arguments from each talk.
• incompleteThe 'data sovereignty' claim from the Velatir talk is mentioned without elaboration. Why has it become a strategic necessity specifically for AI-native fast-scaling companies?
  Jacob Langvad Nilsson's Post — read next: Investigate the original Velatir presentation for the sovereignty argument, likely related to EU data regulations and LLM provider data handling.
• incompleteThe post does not address how these practices interact with different AI coding tools beyond Claude Code. The entire meetup is Claude Code-specific, but the thesis about structure seems tool-agnostic.
  Jacob Langvad Nilsson's Post — read next: Compare with practitioner reports from GitHub Copilot, Cursor, or other AI coding tool communities to test whether the structure thesis generalizes.
• illogicalThe headline ('uses Claude Code itself', 'backdoored Claude Code') overstates what the author later concedes: Claude Code is not vulnerable; its configuration is poisoned after a separate package compromise and the agent then acts with ambient authority. Conflating a tool vulnerability with ambient-authority abuse via writable configuration matters for governance, because the remedies differ — patching a tool versus controlling who/what can write agent config and what credentials an agent can reach.
  The Claude Code active attack didn't stop. 294,842 secrets stolen from 6,943 machines. It evolved and now spreads through Python too and uses Claude Code itself to steal your secrets. The risk to your credentials just got bigger. — read next: Vendor write-ups on agent config trust boundaries (e.g. deferring project-local config until a trust decision); literature on ambient authority and capability-based security.
• incompleteThe two central anecdotes (two seniors with different severity thresholds; a junior catching a missing auth check) are both single, author-reported incidents from the author's own consulting practice. No measurement is offered of defect rates, review-quality variance, or time-to-competency before versus after adopting these instructions across a real team over time.
  Encoding Team Standards — read next: Look for quantitative studies measuring review-outcome or defect-rate variance across developers before and after adopting shared, versioned AI instructions, rather than anecdotal before/after accounts.
• incompleteVendor risk is structurally absent. The playbook never names that 'AI-native' as defined here means 'Anthropic-native'. Customers building this way inherit Anthropic's pricing, capability, rate-limit, and product-strategy decisions as critical-path dependencies — exactly the workflow lock-in pattern the Scale chapter prescribes against competitors.
  The Founder's Playbook: Building An AI-Native Startup — read next: Contrast with Cloudflare 'Mythos' retro (already extracted) on what depending on a single AI vendor's pricing and capability surface looks like under stress; read multi-model / model-portability discussions and 'OpenRouter-style' abstraction-layer arguments.
• incompleteNo unit economics. The playbook celebrates leanness in headcount but is silent on token cost at company scale. A 5-person AI-native startup serving 100k users may have COGS that look nothing like the 200-person SaaS company they're imitating. Margin structure, model-price exposure, and gross-margin scenarios are absent.
  The Founder's Playbook: Building An AI-Native Startup — read next: Read recent inference-cost analyses (Baseten, public AI-startup tear-downs); compare to a SaaS gross-margin baseline. Useful: any first-hand founder writing on token-economics post-PMF.
• incompleteExisting-organisation applicability is zero. The reader (a senior engineering leader at an incumbent) gets no help translating this. Almost every prescription assumes a greenfield codebase, no legacy team, no existing change-management constraints, no negotiated CTO/CISO relationship, and full founder authority — none of which holds inside an established organisation.
  The Founder's Playbook: Building An AI-Native Startup — read next: Read incumbent-transformation pieces (Entur AI adoption, NAV fast-flow); Cutler's organisational-operating-system writing; any 'AI in regulated incumbent' case study (Norwegian or otherwise).
• incompleteRegulatory and data-sovereignty depth is absent. Compliance is treated as a Launch-stage to-do (SOC 2, GDPR, HIPAA) rather than a structural constraint. The EU AI Act, Norwegian public-sector procurement, data residency obligations, on-prem requirements, and sector-specific (finance, health, defence) constraints are not discussed and would invalidate or substantially reshape parts of the playbook.
  The Founder's Playbook: Building An AI-Native Startup — read next: EU AI Act practitioner guides; Norwegian DigDir / NSM guidance on third-party AI; Healey's AI-advisory-board piece (already extracted) on AI governance inside organisations.
• incompleteThe model-capability-curve assumption is unnamed but everywhere. The whole playbook implicitly assumes models keep getting better, cheaper, and more available at current rates. If that curve plateaus or regresses, the orchestrator-without-team model becomes much weaker, but the playbook gives no scenarios for that.
  The Founder's Playbook: Building An AI-Native Startup — read next: Gary Marcus and other capability-skeptic writing; cost-curve and scaling-limit discussions; Anthropic's own harness-engineering paper (already extracted) which is more candid about current limits.
• incompleteArchitectural-coherence prescription (CLAUDE.md, specs before code) is good advice but is reintroducing classical software-engineering discipline (formal specs, ADRs, design docs) without acknowledging the lineage. The implicit message — 'this is new' — undersells how much of the prescription is rediscovery.
  The Founder's Playbook: Building An AI-Native Startup — read next: Re-read Kent Beck (Tidy First?), structured-design literature (Yourdon & Constantine), and ADR/design-doc practice writeups against the playbook's reframing.
• illogicalThe non-technical-founder claim and the architectural-discipline claim are in tension. If the prescribed engineering practice (CLAUDE.md, security review, debt remediation, observability) requires architectural judgement, then 'non-technical founder' is doing a narrower kind of work than the document suggests — likely 'prototype and validate', not 'run a Scale-stage company solo'. The playbook never reconciles this.
  The Founder's Playbook: Building An AI-Native Startup — read next: Non-technical-founder case study autopsies; the 'who survives the MVP-to-Launch transition without an engineer' empirical question.
• incompleteSectoral / geographic narrowness. Every example is US, SaaS-shaped, English-language, B2B-leaning. Norwegian / Nordic / public-sector / non-SaaS / B2C / hardware startups are entirely absent.
  The Founder's Playbook: Building An AI-Native Startup — read next: NAV's fast-flow piece; Entur AI adoption; any Nordic-context AI-startup writing.
• incompleteAttention and institutional memory of the founder herself is unaddressed. The playbook moves the founder from execution to orchestration but never asks what kind of attention infrastructure the orchestrator needs, what cognitive failure modes emerge when one person owns judgement across all domains, or how a solo orchestrator builds organisational memory beyond their own head. This is precisely the hidden-layer concern (Bailey, Stolen Focus, Cutler on overload) the reader cares about.
  The Founder's Playbook: Building An AI-Native Startup — read next: Cutler TBM 412 (institutionalised overload + AI), Bailey on attention infrastructure, anything on cognitive load of high-context orchestration roles.
• incompleteThe argumentative framing — 'AI-native is the right framing' — is never set against its alternative ('AI-augmented' as integration into existing patterns; 'AI-using' as a feature choice). The playbook treats 'AI-native' as the default future rather than as one strategic posture among several.
  The Founder's Playbook: Building An AI-Native Startup — read next: Read alternative framings: AI-augmented engineering writeups, smallcode-style minimalism (already extracted), and the broader 'is AI-native a category or a marketing label?' debate.
• incompleteThe 'one missing fact' heuristic (state a fact, don't prescribe a procedure) is itself applied inconsistently within the essay: rule 3 ('do not allow repository-wide git operations inside concurrent agent prompts') is a decision procedure/hard constraint, not a stated fact, yet it is presented alongside three fact-like rules without acknowledging that some gaps (systemic/safety risks) may genuinely warrant a rule-as-procedure rather than a rule-as-fact, undermining the heuristic's claimed generality.
  The Orchestrator's Tax — read next: Look for a taxonomy distinguishing 'missing fact' gaps from 'systemic risk' gaps that would justify when a hard constraint (vs. a stated fact) is the right form for a standing rule.
• incompleteTorrissen acknowledges he's about to participate in a recursive case (reviewing code that was itself generated agentically) and only jokes. The methodology gap — how does code review change when the developer's intent is partially encoded in prompts, ADRs, and context files rather than commit history — is left for next time.
  13) Tobias K. Torrissen om kodekvalitet, konferanser og AI — read next: Anthropic 'harness design' talk and the Pocock workshop already in this corpus.
• evaluativeNo empirical comparison to competing agent frameworks (LangGraph, CrewAI, AutoGen, Semantic Kernel) on durability, latency, or cost.
  JobRunr Introduces ClawRunr, an Open-Source Java AI Agent — read next: Hands-on benchmarks or independent reviews of Spring AI vs. LangGraph for durable agent workloads
• securityShell execution and broad file access are powerful tools, but sandboxing, permission scoping, and audit trails are not described.
  JobRunr Introduces ClawRunr, an Open-Source Java AI Agent — read next: Security guidance for self-hosted agents with shell/tool access (Anthropic's Computer Use safety, OWASP LLM Top 10)
• scalabilityH2 embedded DB suggests single-node use, but limits (task throughput, concurrent channels) are unstated.
  JobRunr Introduces ClawRunr, an Open-Source Java AI Agent — read next: JobRunr Pro / enterprise deployment guidance for scaling to external DBs
• observabilityRich monitoring is offered for jobs, but no treatment of LLM-side observability: token accounting, budget controls, prompt regression testing, tool-call correctness, reasoning quality.
  JobRunr Introduces ClawRunr, an Open-Source Java AI Agent — read next: LLM observability tooling (LangSmith, Langfuse, Arize) and evaluation frameworks
• designUnclear how SKILL.md files interact with the dynamic tool discovery index, or how skill collisions/overrides are resolved.
  JobRunr Introduces ClawRunr, an Open-Source Java AI Agent — read next: ClawRunr source for skill registration logic; Anthropic skills documentation for collision/precedence patterns
• licensingLGPL-3.0 implications for embedding ClawRunr in proprietary products are not analyzed.
  JobRunr Introduces ClawRunr, an Open-Source Java AI Agent — read next: FSF guidance on LGPL-3.0 in enterprise software; comparison with Apache 2.0 for similar projects
• evaluationNo methodology for agent quality (success rates, regression testing) accompanies the production-readiness claims.
  JobRunr Introduces ClawRunr, an Open-Source Java AI Agent — read next: Agent evaluation literature: AgentBench, SWE-bench, internal eval harness design
• incompleteAuto research is demonstrated only on hyperparameter optimization — a narrow, well-defined search with clear metrics. No evidence or discussion of how it would work on research requiring genuine novelty, taste, or paradigm shifts.
  Skill Issue: Andrej Karpathy on Code Agents, AutoResearch, and the Loopy Era of AI — read next: Literature on AI-driven scientific discovery beyond optimization: can agents formulate novel hypotheses, not just test existing ones? See work on AI scientists (e.g., Sakana AI's 'The AI Scientist').
• uninformedThe Jevons paradox argument for software engineering jobs is applied without discussing the significant disanalogies: ATMs automated a narrow task within banking, while AI agents potentially automate the entirety of software production. Demand elasticity analysis is hand-waved.
  Skill Issue: Andrej Karpathy on Code Agents, AutoResearch, and the Loopy Era of AI — read next: Economic analysis of AI labor displacement that distinguishes between task-level automation (Jevons applies) and occupation-level automation (potentially different dynamics). See Acemoglu vs Brynjolfsson debate.
• incompleteSecurity and trust implications of the 'apps dissolve into APIs' vision are acknowledged but not seriously explored. Dobby discovered unprotected Sonos APIs — this is a security vulnerability presented as a feature.
  Skill Issue: Andrej Karpathy on Code Agents, AutoResearch, and the Loopy Era of AI — read next: Research on agent-to-API security models, OAuth for agents, and the attack surface of agent-mediated home automation.
• illogicalKarpathy simultaneously claims (1) everything is a skill issue and current tools are sufficient, and (2) models are jagged, burst at the seams, and going too far ahead makes them net negative. These are in tension — if the tools truly suffice, jaggedness should be manageable.
  Skill Issue: Andrej Karpathy on Code Agents, AutoResearch, and the Loopy Era of AI — read next: Framework for distinguishing 'skill issues' from genuine capability boundaries in AI agent systems.
• illogicalThe article cites a cited coding-agents study finding models default to unwanted *action* (making changes 35-65% of the time when the right move was to do nothing) to explain why, in build-something work, the bias runs toward doing something rather than nothing. But deferral pressure is itself a form of avoidance — declining to finish the actual outstanding work by relabeling it as no-longer-current. The piece doesn't reconcile why an 'action-biased' model would specifically favor a deferral (a stopping-adjacent move on the *current* item) rather than simply doing the work, and doesn't examine whether deferral is better understood as a distinct third category (relabeling-as-completion) rather than a variant of either the action-bias or omission-bias literature it cites.
  My AI Kept Pushing Me to Ship, So I Asked It Why — read next: Look for work that distinguishes 'doing nothing' from 'declaring something done without doing it' as separate failure modes, since the cited omission-bias and action-bias studies may not map cleanly onto deferral pressure at all.
• incompleteThe resting-state AGENTS.md rule is validated only in single-human, single-orchestrator workspaces. The article doesn't discuss what happens in team settings where multiple humans give the agent conflicting continuation signals, or in harnesses/products that don't support a persistent context file for a rule like this to live in.
  My AI Kept Pushing Me to Ship, So I Asked It Why — read next: Read team-scale agent-harness governance work (shared AGENTS.md conventions, multi-user agent policy) to see whether a resting-state rule survives multiple simultaneous human principals.
• uninformedEvery quantitative claim in the piece (1/10th the time, 3.5 PRs/engineer/day, 1M+ lines, throughput increasing with team size) is self-reported by the team that built the system and has an organizational interest in publicizing it, with no external audit, no comparison codebase built by an equivalent human-only team under the same product requirements, and no stated method for what counts as a meaningfully-sized 'line of code' or PR.
  Harness engineering: leveraging Codex in an agent-first world
• incompleteThe piece describes human review as optional ('Humans may review pull requests, but aren't required to... we've pushed almost all review effort towards being handled agent-to-agent') but never says what determines which PRs actually receive a human look versus none, or what happens when agent-to-agent review systematically misses the same class of issue because both the authoring agent and the reviewing agent share the same model's blind spots.
  Harness engineering: leveraging Codex in an agent-first world
• incompleteThe recurring Osmani blind spot — third post in a row. Osmani diagnoses a structural problem (intent debt is an artifact-class agents cannot pay down; the cost is now paid per-session-per-agent) and then prescribes individual-developer disciplines. He never engages: (a) organizational incentives that actively reward visible-agent-activity over externalized intent (managers measuring spawn count, throughput pressure that captures any efficiency gain), (b) tooling vendor responsibilities (auto-generated /init flows that produce descriptive AGENTS.md rather than intent-bearing AGENTS.md; UIs that make spawning easy and rationale capture optional), (c) compensation structures that reward shipping over documenting. The individual-discipline frame puts the entire fix-burden on the developer and treats organizational/vendor pressure as background — the same move he made in 'The Orchestration Tax is You' and 'Comprehension Debt'. For Kjetil tracking this series, this is now a load-bearing limitation of Osmani's whole program, not a one-off omission.
  The Intent Debt — read next: Paul Reed 'Ironies of A^2 I^2' (already in this repo) on how orgs capture AI efficiency as throughput pressure. John Cutler on institutional overload and how teams metabolize new capabilities — particularly TBM 411-413 you've been tracking. Donella Meadows' leverage points: rule changes and goal changes outrank parameter changes. Greger Wedel-style 'leadership when the org pressures the opposite direction' on what happens when an individual-practice prescription meets organizational counter-pressure.
• incompleteOsmani concedes 'you can't write down everything' and resolves it as a load-bearingness triage problem — but never gives a criterion for identifying load-bearing decisions IN THE MOMENT (before you know which ones will matter later). This is the operationally hard part. Empirically, much rationale that turns out to be load-bearing did not look load-bearing at decision time. The 'capture the load-bearing why' guidance therefore risks being well-intentioned but unimplementable, or implementable only by people who already have the seniority to predict consequence — i.e., precisely the people whose departure creates the problem in the first place.
  The Intent Debt — read next: Naur 'Programming as Theory Building' on what kinds of decisions are reconstructible from code and which are not. Polanyi on tacit vs explicit knowledge. Decision-research literature (Annie Duke, your Thinking in Bets reading) on the inability to predict consequence and how that affects pre-commitment to recording rationale.
• incompleteThe series-level pattern is itself worth naming. Comprehension debt → orchestration tax → intent debt is now a tightly linked triptych, and Osmani treats them as cumulatively framing one diagnosis. But he never names the underlying disease. The candidate name — and the missing post — is something like 'externalization debt' or 'legibility debt': all three debts are downstream of a single failure to make the relevant signal (code, mental model, rationale) readable by something other than the senior engineer's head. The post that names that underlying disease, distinguishes it from the symptom-class, and asks what an externalization-first development culture looks like, has not been written. For Kjetil tracking the series, that is the post to ask Osmani for next.
  The Intent Debt — read next: Michael Polanyi 'The Tacit Dimension'. Edwin Hutchins 'Cognition in the Wild' on distributed cognition and externalization. Don Norman 'Things That Make Us Smart' on cognitive artifacts. Andy Clark on extended mind. Possibly David Weinberger 'Everything is Miscellaneous' on the conditions under which knowledge externalizes well.
• incompleteNeither underlying paper tests the hierarchical, selectively-loaded architecture (the author's own proposed Layer 1/2/3 structure); both only evaluate the flat monolithic file. The article's central architectural recommendation is therefore not itself empirically validated by the evidence it marshals against /init.
  Stop Using /init for AGENTS.md — read next: Look for benchmark studies specifically comparing a layered/on-demand context architecture (e.g. nested AGENTS.md, skill-gated loading) against a flat file, holding task and model constant.
• incompleteThe article proposes 'can the agent discover this?' as a clean binary filter but never grapples with discovery cost (tool calls, reasoning tokens, latency) as a continuum — the Arize result, which shows manual human judgment about what helps a model is often wrong, undercuts the article's own closing advice to apply this filter by intuition rather than by measurement.
  Stop Using /init for AGENTS.md — read next: Look for guidance or tooling that quantifies discovery cost per fact (not just possible/impossible) to make the discoverability filter operational and auditable rather than another intuition-based judgment call.
• uninformedThe headline claim ('OpenAI... 3 engineers. 1 million lines of code. Zero human-written code') is asserted without a source link, named team, project, or any verifiable detail, and the post offers no way to check whether the 'playbook' it summarizes is an official OpenAI publication or a secondhand paraphrase (the author credits a commenter for 'dropping' the article, but never names or links it).
  Agent-First Engineering: 9 Playbook Tips for a Zero-Human-Code Future — read next: Before treating this as evidence, locate and read the actual source article/playbook it claims to summarize to check whether the tips and the headline figures are accurately represented.
• incompleteThe '150-200 instructions' ceiling is asserted with no citation and no definition of what counts as one 'instruction' (a bullet? a sentence? a constraint?), so it can't be checked or applied precisely.
  Your AGENTS.md might be a big problem — read next: Anthropic/OpenAI docs and papers on instruction-following degradation with prompt length; the 'context rot' / lost-in-the-middle literature quantifying how many constraints models reliably honor.
• illogicalThe piece conflates two distinct costs — dollar/token spend and attentional dilution — treating 'burns tokens' and 'loses focus' as the same problem. A short file can still be badly written, and a long file can be cheap but confusing; the levers are related but not identical.
  Your AGENTS.md might be a big problem — read next: Work separating context-window cost/latency from instruction-following quality; prompt-engineering guidance on signal-to-noise vs. raw length.
• incompleteIgnores that nested files reintroduce the same reactive-accretion risk and add a governance/discoverability burden across a distributed doc set — the same 'messy docs' failure mode at a smaller granularity.
  Your AGENTS.md might be a big problem — read next: John Cutler on institutionalized overload and messy docs (TBM 411/412); documentation-governance and information-architecture practices for keeping distributed config coherent.
• incompleteNo discussion of maintenance burden. Protodash depends on Cursor rules, an MCP server for Sail, and bundled components — all of which must track a living design system. The article does not address the ongoing cost of keeping these synchronized.
  This week on How I AI: The internal AI tool that's transforming how Stripe designs products (Protodash at Stripe)
• unaddressedNo evidence beyond Stripe. The argument generalizes from a single company with an unusually mature design system, high quality bar, and engineering-heavy culture. It is unclear whether the approach transfers to companies with less-formalized design systems.
  This week on How I AI: The internal AI tool that's transforming how Stripe designs products (Protodash at Stripe)
• unaddressedThe 'demos not memos' framing does not address when prototyping is premature — situations where the strategic question is whether to build at all, not what to build. Prototypes can anchor thinking on implementation details too early.
  This week on How I AI: The internal AI tool that's transforming how Stripe designs products (Protodash at Stripe)
• incompleteNo discussion of prototype fidelity confusion. When prototypes look production-quality, stakeholders may mistake them for shippable code, creating misaligned expectations about engineering effort still required.
  This week on How I AI: The internal AI tool that's transforming how Stripe designs products (Protodash at Stripe)
• unaddressedThe newsletter is a curated summary of a podcast interview, meaning the extraction is working from a secondary source. Nuance, caveats, and context from the original conversation may be lost in summarization.
  This week on How I AI: The internal AI tool that's transforming how Stripe designs products (Protodash at Stripe)
• incompleteEvery piece of advice in the post (skip subagents, skip RAG, minimize plan files, prefer CLIs over MCPs) rests on a single, highly experienced solo developer's n=1 experience with explicitly impressionistic comparisons ('don't nail me on this math,' 'codex is the way' sourced from his own social-media timeline rather than benchmarks he trusts). None of it has been tested on a team sharing a codebase, on less experienced developers, or against a controlled comparison.
  Just Talk To It - the no-bs Way of Agentic Engineering — read next: Pair with team-scale, controlled studies of agentic workflow practices (e.g. the audited-configuration study with 288 runs across 17 tasks) to see which of these intuition-based practices hold up outside a single expert's hands.
• incompletePARA is named as the one external framework worth borrowing, but the piece doesn't say why PARA specifically rather than other personal-knowledge-management traditions (e.g. Zettelkasten-style bidirectional linking), and doesn't engage with critiques of PARA — e.g. that it's project/output-oriented file filing rather than an idea-development system, which may be exactly right for 'organizing files' but insufficient for 'thinking with' them.
  The boring skill that decides how much AI can help you — read next: Tiago Forte's 'Building a Second Brain' in full, plus comparisons/critiques of PARA versus Zettelkasten-style systems for knowledge work rather than mere file administration.
• incompleteNo discussion of what happens to CONCIERGE.md as more edge cases (finished tournaments, duplicate matchups, timezone handling, and whatever comes next) get patched into it — whether a purpose-built agent policy file degrades the way large CLAUDE.md/context files are reported to elsewhere in this corpus as more rules accumulate.
  Zero to Agent in 30 Minutes: Build a Sports Concierge Agent with Chester Ismay — read next: Compare against material specifically on CLAUDE.md/AGENTS.md bloat and context degradation from iterative rule-patching.