DEV Community: Jeremy Rajan

What I've Learned Scaling Engineering Organisations

Jeremy Rajan — Mon, 06 Apr 2026 04:47:46 +0000

Scaling an engineering organisation isn't primarily a technical problem. It's a systems problem — and the system includes people, processes, and culture just as much as it includes code.

After 15 years of building and leading engineering teams across fintech, iGaming, and logistics, here's what I keep coming back to.

Hire for the problem, not the stack

The best engineers I've worked with weren't defined by the languages they knew. They were defined by how they thought about problems. When you're scaling fast, you need people who can reason about trade-offs, not people who happen to know your ORM.

This doesn't mean technical skills don't matter — they do. But the hierarchy is: problem-solving first, system thinking second, specific tech third.

Process should reduce friction, not create it

Every process you introduce has a cost. The question isn't "is this best practice?" — it's "does this make us faster or slower right now?"

I've seen teams drown in ceremony that made sense at a previous scale. Stand-ups that run 45 minutes. Sprint planning that takes half a day. Retrospectives that produce action items nobody tracks.

Good process at scale looks like:

Short feedback loops — deploy often, measure everything, fix fast
Clear ownership — every service, every domain has a name attached
Minimal coordination overhead — if two teams need a meeting to ship a feature, your architecture is wrong

Architecture follows team structure

Conway's Law isn't just an observation — it's a design tool. If you want independent, fast-moving teams, your architecture needs to support that. Shared databases, shared deployment pipelines, shared anything becomes a bottleneck.

The most effective replatforming work I've done started with the org chart, not the system diagram.

Observability is not optional

You cannot scale what you cannot see. Before optimising anything — performance, cost, reliability — you need to know what's actually happening in production.

This means:

Structured logging from day one
Distributed tracing across service boundaries
Dashboards that answer questions, not just display metrics
Alerts that are actionable, not noisy

I've walked into organisations running 100+ services with no centralised logging. The first conversation is always the same: "We need to see before we can fix."

The work is never purely technical

The hardest part of scaling engineering isn't the code. It's getting alignment between engineering, product, and the business on what matters. It's making trade-offs visible. It's saying "no" to the right things so you can say "yes" to the things that actually move the needle.

That's the work I find most interesting — and it's why I do what I do.

If you're dealing with scaling challenges and want to talk through your situation, get in touch.

The views expressed in this article are my own and do not reflect the opinions or positions of my employer.

Originally published at https://jeremyrajan.com/blog/scaling-engineering-orgs/

Writing an AI Skill Definition for Go Backend API Engineers

Jeremy Rajan — Mon, 06 Apr 2026 04:47:41 +0000

In a previous post, I argued that centralised agent skill definitions are the key to scaling AI across an engineering org. In the follow-up, I walked through how to build a context layer that connects your knowledge base to AI tooling.

This post is the next step: what does an actual skill definition look like, why is it opinionated, and how do you enforce it across your entire engineering org?

Why a skill definition matters

Give an AI coding assistant a Go codebase with no context and ask it to add a new endpoint. You'll get something that compiles. It might even work. But it won't match your architecture. It won't follow your error handling patterns. It won't use your shared libraries. It won't write the tests the way your team expects.

The AI doesn't know:

That your transport layer is deliberately dumb — just request mapping, no business logic
That you use ULIDs, not UUIDs
That all dependencies must be passed explicitly — no globals, no init()
That new libraries need approval before being added to go.mod
That integration tests must use testcontainers against a real database, not mocks

Without these rules, every AI-generated PR becomes a code review battle. The reviewer catches the violations, requests changes, the engineer fixes them — and the AI makes the same mistakes next time. You're paying for AI tooling but not getting the leverage.

A skill definition fixes this. It's a configuration file that tells the AI how your team works — the patterns, the conventions, the guardrails. Once it's in place, AI output matches your standards from the first generation.

What we built

We maintain a Go backend service template — a golden path that every backend API service in the organisation is built from. It's opinionated by design. Every API service follows the same layered architecture, the same testing patterns, the same deployment pipeline.

A note on scope: This skill definition covers API services — request/response workloads served over REST, gRPC, or GraphQL. Background workers, event consumers, cron jobs, and data pipelines have different concerns (concurrency patterns, retry semantics, idempotency, backpressure) and deserve their own skill definitions. Don't force a worker into an API template.

The template already encodes our standards in code. But code shows what — it doesn't explain why, and it doesn't tell the AI what's off-limits. That's what the skill definition does.

Here's what we considered when writing it.

The architecture section: encoding the "why"

The first thing the skill definition establishes is the architecture:

transport (REST/gRPC/GraphQL) → usecase → storage

But it doesn't just state the layers — it explains the rules:

Transport layer is dumb. It maps requests to DTOs, calls the usecase, maps the response back. No business logic here. Ever.
Business logic lives in internal/usecase/. This is transport-agnostic. It uses plain Go structs and context.Context.
Storage is behind interfaces. Never use GORM directly in handlers or usecases.
Dependencies are explicit. All handler dependencies are passed as function arguments or struct fields. No globals. No init().

Why so explicit? Because without this, an AI will happily put business logic in a handler, call GORM directly from a resolver, or create a package-level database variable. It doesn't know these are violations unless you tell it.

Adding a new entity: the golden workflow

One of the most common tasks is adding a new domain entity. Without guidance, an AI might start with the endpoint and work backwards. That's wrong in our architecture. The skill definition specifies the exact sequence:

Define the entity and storage interface in internal/storage/database/
Define the usecase (interfaces, DTOs, implementations) in internal/usecase/<entity>/
Wire the transport handlers in internal/transport/{rest,grpc,graphql}/
Register everything in internal/bootstrap/bootstrap.go
Write migrations via make scaffold name=<entity>

Model → usecase → transport → bootstrap. Not the other way around. This is the kind of workflow knowledge that lives in senior engineers' heads. Encoding it means every engineer — and every AI tool — follows the same path.

The library gate: governing dependencies

This is one of the most important sections, and one that most AI configurations miss entirely:

Before reaching for an external library, check if the company shared libs already provide the functionality. This is a hard gate.

We've seen what happens without this rule. Teams independently adopt three different HTTP client libraries, two logging frameworks, and four ways to handle configuration. Each one is individually reasonable. Collectively, they're a maintenance nightmare.

The skill definition makes the approved dependency set explicit — Chi for HTTP routing, GORM for database access, testify for assertions, testcontainers for integration tests. If a library isn't in the template's go.mod, it needs a discussion before it gets added.

This is the kind of organisational guardrail that AI tools will never infer from the code alone.

Testing: non-negotiable

The skill definition doesn't suggest tests. It mandates them:

Tests are mandatory. No exceptions.

And it's specific about what "tested" means:

Unit tests with gomock and testify, colocated with source files, run in parallel
Integration tests with testcontainers against real Postgres — never mock the database in integration tests
Coverage enforced by CI via SonarQube

The distinction between unit and integration tests matters. We got burned in the past when mocked database tests passed but production migrations failed. The skill definition encodes that lesson so no one has to learn it again.

The "never do this" list

Every opinionated system needs explicit anti-patterns. Ours has eight:

Never overhaul the template — the structure is the standard
Never modify .github/ — workflows are synced from the template
Never copy-paste without understanding the structure
Never commit generated code
Never bypass the shared library gate
Never write a handler without tests
Never use raw GORM outside the storage layer
Never hardcode secrets, URLs, or environment-specific values

These aren't aspirational guidelines. They're hard rules. And they're the rules most likely to be violated by AI tools without explicit instruction — because an AI optimises for "working code," not "code that belongs in your system."

PR process: contract first, stack small

The skill definition also encodes how work gets reviewed:

Contract first. Before writing code, agree on the API contract — protobuf definition, GraphQL schema, or OpenAPI spec. The contract is the handshake between teams. Code comes after.

Stack PRs for large features. One concern per PR. If a PR touches usecase, storage, transport, and config simultaneously, it's too big. Break it down: model → usecase → transport → wiring. Each one is a reviewable, mergeable unit.

This is the kind of process knowledge that usually lives in onboarding docs that nobody reads. Putting it in the skill definition means the AI actively follows it — suggesting stacked PRs when the scope gets large, asking about contracts before generating code.

Keeping it centralised: engineers can't change it

The skill definition is only useful if it's consistent across every service. If individual teams can modify their copy, you end up with drift — and drift is worse than no standard at all.

We solve this the same way we handle CI workflows: template sync.

Our service template repository contains the CLAUDE.md file alongside the .github/ workflows. When changes are pushed to the template, they automatically sync to all downstream service repositories. Engineers can't modify the file in their repos — it gets overwritten on the next sync.

engineering-standards/         # Template repo (write access: platform team only)
  ├── .github/workflows/       # CI/CD pipelines
  ├── CLAUDE.md                # AI skill definition (backend-go.md)
  └── ...                      # Template code

payment-service/               # Downstream service repo
  ├── .github/workflows/       # ← synced from template
  ├── CLAUDE.md                # ← synced from template
  └── src/                     # Team's business logic

The platform team owns the skill definition. They iterate on it based on code review patterns — if reviewers keep catching the same AI-generated mistakes, the fix goes into the definition, not into individual PRs.

This creates a feedback loop:

AI generates code → reviewer catches a pattern violation →
platform team updates CLAUDE.md → AI stops making that mistake →
across every service, immediately

That's the difference between fixing a problem once and fixing it everywhere.

The full skill definition

Here's the complete CLAUDE.md we use for Go backend services. It's opinionated, specific, and it works.

Download backend-go.md

Architecture

This codebase follows a clean layered architecture:

transport (REST/gRPC/GraphQL) → usecase → storage

Transport layer is dumb. It maps requests to DTOs, calls the usecase, maps the response back. No business logic here. Ever.
Business logic lives in internal/usecase/. This is transport-agnostic. It uses plain Go structs and context.Context. It never imports transport-specific packages.
Storage is behind interfaces. Never use GORM directly in handlers or usecases. Always go through the repository interface in internal/storage/database/.
Dependencies are explicit. All handler dependencies are passed as function arguments (REST) or struct fields (gRPC/GraphQL). Looking at a handler must tell you exactly what it depends on. No globals. No init().

Adding a new entity/domain

Think in usecases first, not endpoints.

Define the entity in internal/storage/database/ — model struct with the base Model embed (ULID generation), plus the storage interface.
Define the usecase in internal/usecase/<entity>/ — interfaces (Creator, Fetcher, Manager), DTOs, and implementations.
Wire the transport in internal/transport/{rest,grpc,graphql}/ — handlers that call the usecase.
Register in bootstrap — add the new storage and usecase manager to internal/bootstrap/bootstrap.go.
Write migrations — use make scaffold name=<entity> to generate migration files.

The flow is always: model → usecase → transport → bootstrap. Not the other way around.

Code conventions

Structure: Follow the existing package structure exactly. Do not create new top-level packages. Use internal/ for all application code. Only pkg/ for truly reusable utilities. Generated code (mocks, swagger, GraphQL) is never committed.

Naming: Handlers use <Entity><Action> (e.g., CreateTodo). Interfaces use role-based names (Creator, Fetcher, Manager) — not ITodoService. Errors are descriptive (ErrNotFound, ErrInvalidArgument).

Error handling: Errors are transport-specific. Usecases return plain Go errors. Transport layers map them to the appropriate format (HTTP status codes, gRPC AppError, GraphQL gqlerr). Never swallow errors.

Configuration: All config via environment variables with struct tags and sensible defaults. Never hardcode values. Config structs live in internal/config/.

IDs: Use ULIDs, not UUIDs.

Dependencies and libraries

Use shared company libraries first. Before reaching for an external library, check if the company shared libs already provide the functionality. This is a hard gate.

Do not add new libraries without approval. The template defines the approved dependency set.

Testing

Tests are mandatory. No exceptions.

Unit tests: Colocated with source files. Use gomock for mocking, testify for assertions. Run with t.Parallel() where possible. Test behaviour, not implementation.

Integration tests: Use build tag //go:build integration. Use testcontainers for real Postgres and Redis — never mock the database in integration tests. Containers auto-cleanup via tb.Cleanup().

Observability

Observability is wired into the template from the start. Structured logging with context and correlation IDs. Prometheus metrics pre-configured. Health checks at /internal/health and /internal/metrics. Panic recovery built into all transport layers.

Do not add custom observability infrastructure. Use what the template provides.

Performance

Performance is baked in, not an afterthought. But also: KISS. No N+1 queries. Use DataLoaders for GraphQL. Profile before optimising. Keep handlers thin.

What you must never do

Never overhaul the template
Never modify .github/
Never copy-paste without understanding the structure
Never commit generated code
Never bypass the shared library gate
Never write a handler without tests
Never use raw GORM outside the storage layer
Never hardcode secrets, URLs, or environment-specific values

PR process

Contract first. Agree on the API contract before writing code.

Keep PRs small. One concern per PR. Stack PRs for large features: model → usecase → transport → wiring.

CI is the gatekeeper. All tests, linting, secret scanning, and coverage must pass. If CI fails, fix it.

What changed after we shipped it

The most immediate impact was on code review. Reviewers stopped catching the same structural violations. AI-generated PRs started following the architecture — usecases in the right place, dependencies explicit, tests included.

The subtler impact was on junior engineers. A junior with this skill definition gets AI output shaped by 15 years of backend engineering experience. They don't need to know why we use ULIDs or why the transport layer is dumb — the AI already knows, and the code it generates reflects that.

That's the real leverage of centralised skill definitions: you encode your best thinking once, and every engineer benefits from it every day.

This is part of a series on AI adoption for engineering teams. Start with the strategy, then read about building the context layer. If you're building this for your org and want help, get in touch.

The views expressed in this article are my own and do not reflect the opinions or positions of my employer.

Originally published at https://jeremyrajan.com/blog/ai-skill-definitions-go-backend-api/

Building an AI Context Layer for Engineering Teams

Jeremy Rajan — Mon, 06 Apr 2026 04:44:42 +0000

In a previous post, I outlined a four-step AI adoption strategy for engineering teams. The first step — building a knowledge layer — is the one most teams skip, and the one that matters most.

This post is the practical follow-up. How do you actually build that knowledge layer when you have 50+ engineers, hundreds of Confluence pages, thousands of Jira tickets, and dozens of GitHub repos?

The problem: context fragmentation

In any mid-to-large engineering org, knowledge lives in at least three places:

Confluence — architecture decisions, runbooks, domain models, onboarding docs
Jira — what's being built, why, by whom, and what's blocked
GitHub — the code itself, PRs, reviews, comments, API contracts

An engineer working on Service A needs to understand how Service B's API behaves, what the Confluence architecture doc says about the integration, and whether there's a Jira ticket in flight that changes the contract.

Without that cross-service context, AI generates code that compiles but breaks at integration. It's technically correct and practically useless.

The architecture

The setup has three layers:

1. Knowledge index (Onyx) — crawls and indexes your Confluence, Jira, and GitHub data into a searchable vector store.

2. Context bridge (MCP) — a lightweight server that lets Claude Code query the knowledge index on demand.

3. Local guardrails (CLAUDE.md) — per-repo configuration files that define conventions, patterns, and boundaries.

Engineer asks Claude Code to implement a feature
     │
     ├──▶ MCP → Onyx: fetches Jira ticket details
     ├──▶ MCP → Onyx: searches Confluence for relevant docs
     ├──▶ MCP → Onyx: finds related code across all repos
     ├──▶ Local: reads current codebase directly
     └──▶ Local: reads CLAUDE.md for conventions
     │
     ▼
Code generated with full organisational context

Let's walk through each layer.

Layer 1: The knowledge index

You need something that crawls your tools, chunks the content, generates embeddings, and keeps everything in sync. You could build this yourself — the RAG pattern isn't complicated — but at scale, you want something purpose-built.

Onyx (formerly Danswer) is open source, self-hosted, and has pre-built connectors for Confluence, Jira, GitHub, Slack, and Google Drive. You deploy it with Docker, point it at your Atlassian and GitHub credentials, and it handles crawling, chunking, embedding, and incremental sync.

What matters here isn't the tool — it's the principle: centralise your organisation's knowledge into something AI can search. Whether that's Onyx, Glean, or something you build internally, the outcome is the same: a single retrieval layer over everything your team knows.

A few practical notes:

Incremental sync is non-negotiable. You'll have thousands of documents. Full re-indexing on every change doesn't scale. The sync layer needs to track what's changed since the last run.
Metadata matters as much as content. Every chunk needs to be tagged with its source, project, author, date, and type. This lets you filter queries — "only search Confluence" or "only this Jira project" — which dramatically improves relevance.
Stale docs are a real problem. If your Confluence has outdated architecture pages, the AI will confidently use wrong context. Build in a relevance scoring layer, or flag pages that haven't been updated in 6+ months.

Layer 2: The context bridge

Once your knowledge is indexed, you need a way for Claude Code to query it. This is where the Model Context Protocol (MCP) comes in.

MCP is a standard that lets AI tools connect to external data sources through lightweight servers. You build a small MCP server that:

Accepts search queries from Claude Code
Hits your Onyx API
Returns relevant chunks with metadata

The MCP server is configured in your Claude Code settings:

{
  "mcpServers": {
    "org-knowledge": {
      "command": "node",
      "args": ["mcp-onyx-bridge/index.js"],
      "env": {
        "ONYX_API_URL": "https://onyx.internal.yourcompany.com",
        "ONYX_API_KEY": "..."
      }
    }
  }
}

With this in place, when an engineer says "implement PROJ-456", Claude Code can:

Fetch the Jira ticket details, acceptance criteria, and comments
Search Confluence for related architecture docs and domain context
Find how other services handle similar patterns across your GitHub org
Then generate code grounded in all of that context

The bridge is intentionally thin. It's a translator between Claude Code and your knowledge index — not a place for business logic. Keep it simple.

Layer 3: Local guardrails

The knowledge index gives Claude what to know. The guardrails tell it how to behave.

Every repo gets a CLAUDE.md file at its root. This is a plain markdown file that Claude Code reads automatically. It defines:

What this service is and who owns it:

This is the payment-service, owned by the Payments squad.
It processes transactions via Stripe and publishes events to Kafka.

Key dependencies and integration points:

## Dependencies
- webhook-service: receives payment status callbacks (see PROJ-234 for contract)
- notification-service: triggered via Kafka events on payment.completed
- Stripe API: all payment processing goes through our Stripe wrapper in lib/stripe/

Conventions and patterns to follow:

## Conventions
- All API endpoints use the handler pattern in src/handlers/
- Errors must use the AppError class from lib/errors.ts
- Database queries go through the repository pattern, never raw SQL
- All new endpoints need integration tests, not just unit tests

What to never do:

## Guardrails
- Never commit API keys or secrets — use environment variables
- Never bypass the rate limiter middleware
- Never write directly to the payments database from outside this service

This is the centralised agent skills definition from the adoption strategy. When you standardise these files across your org, you get consistent AI behaviour everywhere — same patterns, same guardrails, same quality bar.

How it comes together: a real example

An engineer on the Payments squad picks up PROJ-456: "Add retry logic to payment webhook handler."

They open Claude Code in the payment-service repo and type: "Implement PROJ-456."

Here's what happens:

Claude reads CLAUDE.md — knows this is the payment-service, knows the handler pattern, knows the error conventions
Claude queries Onyx via MCP — fetches PROJ-456 from Jira, gets the description, acceptance criteria, and a comment from the tech lead saying "use exponential backoff, max 3 retries"
Claude queries Onyx for "webhook retry" in Confluence — finds the architecture doc that specifies retry policy and SLA requirements
Claude queries Onyx for related code across GitHub — finds that notification-service already implements retry logic with the same pattern, sees the exact backoff parameters
Claude reads the local codebase — finds the existing webhook handler, the test patterns, the Kafka publisher
Claude generates the implementation — with exponential backoff (not just simple retry), matching the existing notification-service pattern, following the handler convention, with integration tests

That's the difference between "AI that writes code" and "AI that writes code that belongs in your system."

Rollout

Don't try to set up all three layers at once. The sequence matters:

Week 1–2: Deploy Onyx. Connect Confluence, Jira, and GitHub. Let it index. Validate that search results are relevant. This is your foundation — if the knowledge layer is bad, everything built on top of it will be bad.

Week 3: Build the MCP bridge. A thin server that queries Onyx. Test it with Claude Code on one repo, with one senior engineer. Iterate on the query patterns — you'll learn what context Claude actually needs vs. what's noise.

Week 4–5: Write CLAUDE.md files for key repos. Start with 3–5 high-traffic repos. Have the senior engineers who own those repos write them. These files encode years of tribal knowledge into something AI can use.

Week 6+: Expand. More repos, more engineers, more refined guardrails. The senior engineers who piloted the setup become the advocates.

The unglamorous truth

None of this is technically hard. Docker, a small MCP server, and some markdown files. The hard part is organisational:

Getting Confluence clean enough that AI doesn't hallucinate from outdated docs
Getting engineers to write and maintain CLAUDE.md files
Getting leadership to invest in the indexing infrastructure before they see results

But the teams that do this work end up with something genuinely powerful: AI that doesn't just write code — it writes code that understands why the code exists, how it fits into the system, and what constraints it needs to respect.

That's the context layer. And it's the difference between AI as a toy and AI as infrastructure.

Next up: Want to see what a real skill definition looks like? Read Writing an AI Skill Definition for Go Backend Engineers — the full file, the reasoning behind it, and how to enforce it across your org.

This is the practical companion to A Practical AI Adoption Strategy for Engineering Teams. If you're building this for your org and want help with the setup, get in touch.

The views expressed in this article are my own and do not reflect the opinions or positions of my employer.

Originally published at https://jeremyrajan.com/blog/ai-engineering-context-layer/

A Practical AI Adoption Strategy for Engineering Teams

Jeremy Rajan — Mon, 06 Apr 2026 04:44:40 +0000

Most organisations start their AI adoption journey by buying a tool and hoping engineers figure it out. That's backwards. The tool is the easy part — the hard part is giving AI enough context to be genuinely useful, and enough guardrails to be safe.

After helping engineering teams integrate AI into their workflows, here's the approach I keep coming back to.

Step 1: Build a knowledge layer over your codebase and docs

Before you can get meaningful output from any AI system, it needs to understand your world — your architecture, your conventions, your domain language. Without that context, you get generic answers that sound plausible but miss the point.

This means building a retrieval layer over your existing knowledge:

Documentation — architecture decisions, runbooks, onboarding guides, API specs
Code — repository structure, naming conventions, shared libraries, deployment configs
Institutional knowledge — the stuff that lives in Slack threads and senior engineers' heads

In practice, this looks like setting up RAG (retrieval-augmented generation) pipelines, embedding your docs and code into searchable vector stores, or curating structured context files that AI tools can reference. Some teams go further and build proper knowledge graphs with explicit relationships between systems, teams, and domains — but you don't need that on day one.

The point is: context before capability. An AI tool with deep context about your specific codebase will outperform a more powerful model that knows nothing about how you work.

Step 2: Start small — solve specific problems, not everything

Once your knowledge layer exists, resist the temptation to go big. Pick narrow, well-defined problems where AI can deliver value quickly and where failure is cheap:

Generating boilerplate code that follows your existing patterns
Writing and updating tests for existing functionality
Summarising pull requests or flagging potential issues in code review
Answering developer questions about internal systems using your docs

Each of these is small enough to ship in a week, visible enough to build confidence, and — critically — scoped enough that you can evaluate whether the output is actually good.

This phase is really about iterating on how you define what AI can do. Every time you solve a small problem, you learn something about how to describe tasks, what context the model needs, and where it falls short. Those learnings compound.

Step 3: Centralise your agent skill definitions

This is where most teams skip ahead, and it's where the real organisational leverage lives.

As you solve more problems with AI, you'll accumulate a set of instructions, prompts, tool permissions, and behavioural constraints — what I call skill definitions. These define what an AI agent can do, how it should do it, and what it should never do.

Left decentralised, every team invents their own. You end up with inconsistent quality, no shared guardrails, and no way to audit what AI is actually doing across the organisation.

Centralising these definitions gives you:

Consistency — every team's AI tooling follows the same conventions and standards
Guardrails — you control what actions AI can take (read-only vs. write, internal tools vs. external APIs, which repos it can modify)
Auditability — a single place to review and update what AI agents are permitted to do
Reusability — a skill definition that works well for one team can be shared across the organisation

In practice, this looks like maintained configuration files, shared prompt libraries, or a platform team that owns the AI tooling layer. The specifics depend on your stack — but the principle is the same: treat AI agent behaviour as infrastructure, not individual preference.

Step 4: Pilot with senior engineers before going wide

When you're ready to expand, don't roll out to everyone at once. Start with your most experienced engineers.

This isn't about gatekeeping — it's about feedback quality. Senior engineers can:

Spot hallucinations — they know the codebase well enough to catch when AI confidently generates something wrong
Evaluate trade-offs — they can judge whether AI-suggested code is merely correct or actually good
Refine skill definitions — their feedback directly improves the guardrails and instructions for everyone else
Build trust — when senior engineers vouch for a tool, adoption across the team follows naturally

Run the pilot long enough to iterate on your skill definitions at least two or three times. The goal isn't just to validate that the tool works — it's to harden the configuration so that when less experienced engineers use it, the guardrails are already in place.

Only then do you open it up to the wider team — with documentation, training, and clear expectations about what AI is good at and where human judgement is still required.

The meta-lesson

The pattern here is deliberately boring: build context, start small, centralise control, expand carefully. It's the same playbook you'd use for any significant infrastructure change — because that's what AI adoption is. It's not a product launch. It's a change to how your engineering organisation operates.

The teams I've seen succeed with AI aren't the ones that adopted the fanciest tools first. They're the ones that did the unglamorous work of building context and defining boundaries before scaling up.

Next up: If you want the practical, hands-on version of this — how to actually connect Jira, Confluence, and GitHub to Claude for context-aware code generation — read Building an AI Context Layer for Engineering Teams.

If you're thinking through AI adoption for your engineering team and want to pressure-test your approach, get in touch.

The views expressed in this article are my own and do not reflect the opinions or positions of my employer.

Originally published at https://jeremyrajan.com/blog/ai-adoption-strategy/