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 giv

·AI champion is designated per team with allocated time (not just informal interest)
·Context engineer role exists (initial, possibly part-time) for maintaining agent instruction files
·Developer training on effective agent interaction (prompt writing, task decomposition) has been conducted

·Champion has a regular cadence for sharing learnings across the team
·Training materials are documented and available for new hires

Evidence

·Team roster showing designated AI champion with time allocation
·Context engineer role assignment (even if combined with other duties)
·Training session records or materials

What It Is

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.

Why It Matters

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.

Getting Started

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.
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.
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.
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.
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.
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.

Tip

The best source for initial CLAUDE.md content is not a documentation sprint - it's PR review comments. Go through the last 50 PR reviews and collect every comment that says "we don't do it that way here" or "you need to use X pattern instead." Each of those comments is a context item that an agent (and a new human developer) would have gotten wrong.

6 steps to get from here to the next level

Common Pitfalls

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.

Mistakes teams actually make at this stage - and how to avoid them

How Different Roles See It

BobHead of Engineering

Bob has a champion on each of his four teams who has been doing some ad-hoc context work - mostly writing prompts for themselves and occasionally helping colleagues. Bob can see that the context work is producing results but it's fragmented: each champion has developed their own approach, the quality varies widely, and none of it is being shared across teams.

What Bob should do: Bob should designate the best of the four champions as the initial context engineer for the organization and give them 30% time allocation for context work. Their first deliverable should be a standard CLAUDE.md template and process that the other three champions can adapt to their teams. This creates consistency without imposing uniformity - each team's CLAUDE.md will be specific to their codebase, but the structure and the process for maintaining it will be shared. Bob should set a six-month goal: all four teams have active, maintained CLAUDE.md files and a prompt template library. The context engineer reports progress monthly.

What Bob should do - role-specific action plan

SarahProductivity Lead

Sarah has been asked to develop the organizational capability for context engineering across a 120-person engineering organization. She needs to understand what context engineering actually involves before she can design the career path, the training, and the tooling support for it.

What Sarah should do: Sarah should spend two weeks shadowing the people who are already doing context work across the organization's teams. What are they actually doing day to day? What skills does it require? What tools do they use? What makes the difference between good and mediocre context? This direct observation will produce a better capability definition than any theoretical analysis. Sarah should then write a job description for the context engineer role - not necessarily to hire for it immediately, but to make the function concrete. A clear job description creates a target for skill development, a basis for performance conversations, and a signal to the organization that this function is valued.

What Sarah should do - role-specific action plan

VictorStaff Engineer - AI Champion

Victor has been doing context engineering work as part of his champion role and has become genuinely expert at it. He's written CLAUDE.md files that have measurably reduced agent errors, built a prompt template library that the whole team uses, and developed a systematic process for identifying and closing context gaps. He's starting to think this could be a distinct career track.

What Victor should do: Victor should make his expertise portable. He should write up his process - the CLAUDE.md audit approach, the PR comment mining technique, the feedback loop structure - as a guide that any developer could follow. This is not just helpful to the organization; it's Victor's professional investment. The ability to make AI agents effective in complex, real-world codebases is a scarce and valuable skill. Documenting and systematizing his approach makes it reproducible, which makes it teachable, which positions Victor as the person who defines how context engineering is done in this organization. That's a much more interesting career position than "the developer who's good at AI prompts."

What Victor should do - role-specific action plan