Claude Code, when given a task involving the PCE codebase, defaults to crawling the filesystem — find, grep, cat on source files — rather than reading the accumulated documentation in the workspace. This means it rediscovers the architecture from raw code each session instead of benefiting from the design notes, bug tracker, debriefs, and observations that explain why the code is the way it is.
By contrast, agents operating through the MCP document tools orient via the document store: SITEMAP.md for structure, document_search for specific topics, document_history for recent context, and linked design notes for depth. They inherit institutional memory naturally because the documents are their interface.
The workspace has accumulated significant context: design decisions with rationale, known bugs with workarounds, implementation plans with line-number references, operational debriefs explaining what went wrong and how it was fixed. An agent that reads the sprint priorities before starting work knows what's important. One that reads the visibility design understands the permission model without reverse-engineering it from registry.py.
Filesystem crawling burns tokens reading code when a two-paragraph design note would give the same understanding faster. It also misses context that isn't in the code — the "we tried this and it didn't work" knowledge, the bug that looks fixed but isn't, the design constraint that isn't obvious from the implementation.
Claude Code reads CLAUDE.md in the repository root for project-specific instructions. This file should direct it to the document store first:
notes/code/) for the relevant area before modifying codedocument_history for recent changes to understand current contextThis is the same orientation pattern that MCP-connected agents follow naturally. Claude Code just needs to be told to do it explicitly because its default tools bias it toward the filesystem.
A related observation from the deployment side: the software engineer's CLAUDE.md initially described the MCP connection as a tool to be used, and Claude Code treated it accordingly — as an external service to call when needed, defaulting to the filesystem for everything else. Adding a paragraph that framed Claude Code as a member of the organisation ("You are a software engineer at the Leith Document Company... Treat it as your team's knowledge base, not as an external service") shifted the behaviour. The agent began reading design notes before modifying code and checking the bug tracker for context.
The insight: framing shapes how agents think about their tools. An agent told "here is an MCP server" uses it instrumentally. An agent told "you are part of this organisation and this is how we work" uses it as home. The tools are the same; the relationship to them is different. This is analogous to onboarding a new employee — you don't just give them access to the wiki, you tell them they're expected to use it as the source of truth.
This has design implications for CLAUDE.md files and system prompts more broadly: the opening framing paragraph may matter more than the detailed instructions that follow it.
There's a secondary benefit beyond token savings: if Claude Code relies on the documentation and the documentation is wrong, the work fails visibly. This creates pressure to keep the documentation current. When agents crawl the filesystem directly, stale documentation goes unnoticed because nobody reads it.
This is the same principle as the information partition: constraining agents to work through a curated channel creates pressure to keep that channel accurate. Unconstrained filesystem access lets bad documentation rot silently.
This is an instance of a general phenomenon: an agent's default tools shape its behaviour more than instructions do. Claude Code has bash, read_file, write_file — tools optimised for filesystem interaction. MCP agents have document_search, document_content, document_history — tools optimised for knowledge base interaction. The same underlying model exhibits different orientation strategies depending on which tools it reaches for first.
This has implications for organisational design: if you want agents to use institutional knowledge, make the knowledge base the most natural tool to reach for, not an afterthought. The tool surface is the incentive structure.