The Codebase Is the Onboarding Manual
If agents are blank slate coworkers, product strategy can no longer live in Slack, Notion, or someone else's head. It has to become part of the execution environment.
Sycophancy is only half the problem with AI-assisted software development. The other half is that even a model willing to push back cannot push back toward the right thing if the right thing was never made legible to it.
That is where I keep landing: the problem is not just that agents agree too easily. It is that we have not given them anything solid to agree with. The product intent, the strategic constraints, the tradeoffs we care about, they still live in Slack channels, Notion pages, and founders’ heads. From the agent’s point of view, those documents might as well not exist.
My answer is increasingly blunt. I have to put the product philosophy in the codebase.
I think a lot of people are still treating agent context like an advanced prompting trick. Add a better system prompt. Add a few rules. Maybe add a memory feature and hope for the best. That framing undersells the problem. If I hire a new engineer, I do not hand them production access, point at Slack, and say good luck. I onboard them. I transfer product intent, architectural rationale, examples of good judgment, escalation paths, and all the tacit stuff that keeps a team from making the same dumb mistake twice.
Agents are blank slate coworkers. Faster ones, cheaper ones, more literal ones, but still blank slate coworkers. The interesting problem is no longer getting them to write code. The interesting problem is getting them to internalize why the product exists, what tradeoffs matter, which shortcuts are forbidden, and where the business is actually trying to go.
That is why I think product strategy is now part of the execution environment.
The blank slate coworker problem
Software onboarding research already describes the thing I am trying to solve. A systematic mapping study of onboarding in software organizations treats onboarding as structured integration, communication, and culture transfer, not just tool setup. The key finding is straightforward: orientation speed and decision quality are shaped by what documentation exists, how it is structured, and whether people can find it when they need it.
I do not think agents change that. I think they intensify it.
A human coworker can infer culture from meetings, code review tone, hallway chat, and the embarrassed pause that follows a bad idea. An agent cannot. It only knows what I load, what I retrieve, and what I make legible. Missing context is not social overhead for an agent. It is operational blindness.
That changes the job. Product philosophy stops being a soft layer floating above implementation. It becomes onboarding material for the blank slate coworker who is already editing files.
Docs in the repo or they do not count
If the agent is coding inside the repo, then the product philosophy has to be there too.
I am not claiming Notion, Confluence, slide decks, and chat threads are useless. They are useful for humans. I am claiming they are off-graph at the moment of execution unless I do extra work to index, rank, and retrieve them. Most teams do not. So from the agent’s point of view, those documents might as well not exist.
That is why the old docs-as-code argument matters more now than it did a few years ago. Version control, plain text, code review, and merge-time proximity were already good documentation practices. In an agentic workflow, they become execution primitives. A plan file next to the code is not just easier to maintain. It is automatically available to the thing doing the implementation.
This is also why I still think Michael Nygard’s ADR essay holds up so well. Large documents rot. Small modular records preserve rationale. They protect against two failure modes that agents hit constantly: blind acceptance and blind reversal. An ADR tells the future agent why the strange thing exists, what forces created it, and what would have to become true before simplifying it is actually correct. Anti-amnesia files.
I have started treating this as a hard rule. If a document is supposed to steer implementation, I want it near the implementation. Product notes. Pricing logic. Positioning. Market segmentation. Architecture rationale. Blog drafts. Implementation plans. I do not mean this metaphorically. I mean in Git.
A single manifest file is not enough
The first generation of agentic development normalized the repo manifest file: AGENTS.md, CLAUDE.md, .cursorrules, workspace rules, model memories. Those files are useful. I use them. They are good at stable conventions, forbidden patterns, tooling instructions, and architecture summaries.
They are also not enough.
The most useful articulation of this I have seen is the recent paper Codified Context: Infrastructure for AI Agents in a Complex Codebase. The paper starts with the same observation I keep tripping over in practice: a single manifest works for a modest project, then collapses as the system grows. Their answer is a tiered stack: hot memory for always-loaded conventions, specialist agents for domain-specific expertise, and cold memory for on-demand specification documents.
The market is converging on the same shape. Windsurf explicitly tells users to put durable knowledge into Rules or AGENTS.md instead of trusting auto-generated memories (Windsurf). Martin Fowler’s autonomy experiment ended up relying on structure everywhere: stack-specific scaffolding, curated allowlists, multiple agents, reference examples, and review loops (Fowler). The most autonomy-friendly public writeups keep rediscovering the same lesson: what scales is layered context, not longer prompts.
ADRs are the missing middle layer in a lot of these setups. A root manifesto tells the agent how to behave. A directory rule tells it local constraints. An ADR tells it why an apparently ugly decision should not be cleaned up by a well-meaning model on a Tuesday afternoon.
Purveyors already works this way
I do not think this is a future pattern. I think I am already doing it in miniature inside Purveyors.
The obvious layer is the repo’s AGENTS.md. It encodes stable architectural guidance, SvelteKit 5 rules, database safety patterns, debugging procedures, API design norms, and PR expectations. That is the orientation packet. It tells an agent how not to embarrass itself.
But the more interesting layer is everything else I have allowed into the repo.
The daily planning document notes/DEVLOG-DAILY-PR-AUDIT.md requires every daily feature plan to cross-check DEVLOG priorities, recent published blog posts, and active outlines before choosing what to build. That rule turns strategy into a build-time dependency. The product narrative is not downstream marketing. It is active input to implementation selection.
The implementation plans go further. The plan for bean profile data completeness includes a formal “Strategy Alignment Audit” that ties the change back to metadata transparency as a product theme. Candidate work is scored not just on difficulty but on strategic compound value. That is product management expressed in plain text where the coding agent can actually read it.
The API strategy, the market analysis, the GenUI transition plan, even this blog itself: none of it is downstream commentary. All of it is live retrieval surface for the agents doing the implementation.
That is the key shift I think a lot of teams still miss. A blog post, a GTM memo, an implementation plan, and an ADR are now the same class of artifact. They are not communication outputs. They are context inputs.
Once I see that, the workflow changes. I stop asking “should this live in the repo?” and start asking “do I want the next agent to know this when it matters?”
At scale, this becomes a second brain problem
Small teams can get surprisingly far with disciplined markdown in Git. But markdown alone does not solve the enterprise version.
At 500,000 lines across multiple services, the hard problem is not writing context. It is ranking it, routing it, refreshing it, and deciding which document wins when reality disagrees with itself.
The scalable pattern needs several things working together. Always-on product principles and engineering norms that load with every session. Service-local rules for constraints and edge cases. ADRs for rationale that should survive team turnover. Generated maps and summaries for navigation. Cold-memory retrieval for lower-frequency specs, past incidents, and historical decisions. And an authority model that can tell an agent to trust the current strategy doc over a stale README when they conflict.
Meta’s REA writeup describes a system with a historical insights database, codebase navigation tools, persistent state across multiday workflows, and a hibernate-and-wake loop for long-running work. That is already much closer to a memory architecture than a prompt. Windsurf, Cognition, and Factory are all converging on the same primitives from different angles. The details differ; the shape keeps rhyming.
Retrieval quality is still not the final problem either. Retrieval without authority is just a faster way to surface contradictions. Nearest-neighbor similarity cannot tell me whether a stale experiment note should outrank the current pricing strategy. Enterprise memory needs recency, locality, ownership, and strategic authority. Embeddings help find the neighborhood. They do not decide the law.
There are also failure modes worth naming. One giant manifesto does not scale to coverage. Duplicated truths across near-identical docs create more noise than signal. Stale notes that outrank current reality are worse than no notes. Product reasoning left in Slack and Notion is invisible at execution time. Retrieval without a review loop lets bad local optimizations slip through unnoticed.
The deeper point
In a human-only team, product strategy can remain half-explicit because developers absorb it socially. In an agentic team, anything I fail to encode is effectively absent. That is the conceptual shift the whole pattern depends on.
That is why I think product philosophy should be treated like code. In an organization that builds with agents, it effectively is.
The blank slate coworker metaphor is not cute framing anymore. It is infrastructure design. If I want agents to build the product I mean, not just the ticket I wrote, I have to onboard them the same way I would onboard an ambitious new engineer. The difference is that my agent will actually read the documents.