Context engineer role (initial)

Context engineering is the practice of making information legible to AI agents: writing CLAUDE.md files that explain codebase conventions, building MCP server integrations that give agents access to internal tools, creating documentation structured for machine consumption, and establishing the prompt patterns that make agents effective in a specific technical environment. At L2, this work begins to emerge as a distinct function rather than something individual developers do ad-hoc. The "initial context engineer" is often the AI champion who has graduated into more systematic context work.

The initial emergence of context engineering happens because teams discover that agent quality is not primarily a function of the AI model - it's a function of how well the agent understands the environment it's working in. A developer who has spent two years on a codebase produces better code than a new hire on day one, not because they're smarter but because they know the patterns, the conventions, the landmines, and the history. An agent given that institutional knowledge in its context window produces proportionally better results. Context engineering is the systematic process of providing that knowledge.

At the initial L2 stage, context engineering is typically one person doing four things: maintaining CLAUDE.md files, building a library of effective prompt templates, documenting the implicit conventions that experienced developers know but haven't written down, and experimenting with what kinds of context most improve agent output. This is not a full-time role at L2 - it's typically 20-30% of a senior developer's time. But it is a distinct, named function with ownership, deliverables, and feedback loops.

The transition from "AI champion does some context work" to "context engineer as a recognized function" is primarily a naming and scoping change. The work becomes formalized: there is an owner, a backlog of context improvements, and a measure of context quality. At L3, this function becomes a full role. At L2, it's the beginning of the capability that L3 will systematize.

Context engineering as a function - even in its initial, informal state - produces measurable differences in agent effectiveness:

• Reduces agent error rate - agents working with good codebase context produce fewer convention violations, fewer wrong pattern applications, and fewer assumptions about data models that turn out to be wrong; the error rate difference between barren-context and well-contextualized agents is typically 50-70%
• Scales individual expertise to the whole team - when a senior developer's implicit knowledge is encoded in context documents, every developer on the team (and every agent they run) benefits from that knowledge; knowledge that was previously trapped in one person's head becomes a shared organizational asset
• Removes the "discovery tax" from new team members - the context infrastructure that makes agents effective also makes onboarding faster; a new developer who reads the CLAUDE.md files gets oriented to the codebase conventions faster than one who learns by reading the code
• Creates a foundation for L3 automation - the context infrastructure built by the initial context engineer at L2 is the raw material for L3 automation: MCP servers that feed context to agents automatically, lint rules that enforce the documented conventions, CI checks that validate agent output against the standards
• Makes AI failures diagnostic - when agents fail with good context, the failure is informative: it reveals a gap in the context, a task type that needs better template support, or a genuine limitation of current AI capabilities. Without good context, failures are noise.

1. Identify what context agents most need - run an audit of recent agent failures and classify them: convention violations (agent didn't know the team's patterns), data model errors (agent made wrong assumptions about the schema), API misuse (agent used an internal library incorrectly). Each category points to a specific context gap.
2. Start with CLAUDE.md - the CLAUDE.md file in the repository root is the highest-leverage starting point. A good CLAUDE.md covers: project overview, tech stack and key dependencies, architectural patterns, coding conventions, test patterns, and "things that look wrong but are intentional." This file should be written by someone with deep codebase knowledge, not a newcomer.
3. Build a prompt template library - collect the 10-15 most common agent tasks for the team. For each, write a canonical prompt that includes the right context references and produces consistently good results. Store these in a shared location (a /prompts directory in the repo or a team wiki page). Templates reduce the "what should I tell the agent?" cognitive overhead for every developer.
4. Document the implicit conventions - every codebase has conventions that experienced developers follow but have never been written down. "We use service objects for business logic, not models." "Error messages are always logged before being returned." "Auth checks happen in middleware, never in the endpoint handler." These need to be written down to be useful to agents.
5. Establish a feedback loop - create a lightweight mechanism for team members to report context gaps: a Slack channel, a shared doc, a label in the issue tracker. When an agent produces something wrong because of a missing convention, that gap should be captured and fixed in the CLAUDE.md rather than just corrected in the PR.
6. Measure context quality over time - track agent error rate per category (convention violations, data model errors, etc.) each sprint. As context improves, these rates should decline. This measurement justifies the context investment and guides prioritization of context work.

Treating context engineering as documentation work. Context engineering is not the same as writing developer documentation. Documentation is written for humans who can interpret, infer, and ask questions. Context for agents needs to be precise, unambiguous, and structured. An agent given "follow our normal patterns" does nothing useful with that instruction. An agent given "use the Repository pattern as implemented in UserRepository.java, never access the database directly from service classes" has something to work with.

Building context in isolation. The context engineer who writes CLAUDE.md files without asking developers "what do agents get wrong most often?" is guessing at priorities. Context engineering is most effective when there is a continuous feedback loop between agents' mistakes and context improvements. The feedback loop requires that developers report agent failures, which requires that reporting be easy and that improvements be visible.

Failing to keep context current. Context written today will be outdated in six months as the codebase evolves. A CLAUDE.md that describes the old authentication pattern after a security refactor will actively mislead agents. Context engineering requires a maintenance process: when major code changes happen, the context documents need to be reviewed and updated. This is easily forgotten if no one owns it.

Confusing context engineering with prompt engineering. Prompt engineering is about the specific instructions in a task request. Context engineering is about the ambient information available to the agent throughout all tasks. Both matter, but they're different interventions. The initial context engineer should be building the ambient context - the CLAUDE.md files, the documentation structure - rather than just refining individual task prompts.

Not escalating infrastructure needs. The initial context engineer will quickly discover that some context would be better delivered automatically (via MCP servers) rather than written in static documents. When the context engineer identifies these opportunities, they need a path to get the infrastructure built - either by building it themselves or by escalating to a platform team. Without this escalation path, the context engineer is limited to static documents when dynamic context delivery would be much more powerful.