YouboughtClaude.Theteamdidn'tchange.
Practitioner's framework for CTOs and founders. AI-driven is a way of working, not a toolset. What environments make it scale, what doesn't, and how teams change shape around it.
Most leaders stop where the real work starts
You give a senior engineer Claude Code. The first week feels like superpowers. Things that used to take half a day take twenty minutes. Refactors nobody had touched in two years quietly happen over a weekend. Tests get written. The PR description writes itself.
The second week is similar. By the end of the month, that engineer is shipping somewhere between 2x and 4x of what they were shipping before — measured on lead time for the work they own end-to-end, not LOC or PR count. Everyone's happy. You start telling other CTOs you've "rolled out AI."
Then it plateaus.
The same engineer is still 2x. The team around them isn't. Juniors got Claude too, and they're producing code that runs but doesn't fit anything. The PM is still writing PRDs in Confluence the agent never reads. QA is still a manual pass at the end. Postmortems still get filed in a Notion folder nobody opens. One person learned how to drive the agent. The environment around them never caught up.
"We bought Claude Code for everyone. A month later they came back — why hasn't anything changed?"
If PRDs live in Confluence and update once a week, the architecture lives only in someone's head, QA is a manual pass after the feature ships, and skills live in everyone's personal chats, no Claude Code will save you. It accelerates what works. It accelerates the mess too.
This is where most companies stop. The conclusion is usually "AI works for some roles, not others," or "we'll revisit it next year." Neither is true. The environment is still the one you had before Claude existed, and Claude is now the only thing in it that moved.
Tools are the easy part. The environment around them is the work. Everything below is about building it.
Three beliefs the team has to actually hold
Without these, nothing in the next sections holds together. If on any of them the team's reaction is "agreed in theory," that's the place to return to before rolling out processes.
- 01
AI is a working tool for every role
Product, engineering, QA, analytics, design. If AI is only "for developers," half your bottlenecks stay put and the other half just move into the dev queue.
- 02
Skills and context decide, not the model
Ninety percent of bad AI output is missing context, not a weak model. The team's expertise has to live in code: skills, repo specs, ADRs. The agent picks it up automatically when it does.
- 03
Leaders build the environment
Senior engineers spend their time designing the platform, skills, and conventions that make mids and juniors fast. They stop being the best individual contributors. They become the reason everyone else can be.
Where the agent isn't going to save you
Before building the environment, name what it won't fix. Some categories of work the agent still does badly. Pretending otherwise is how you ship slow code and live with it.
A year ago I wrote up a small trick we'd come up with: fast SELECTs over millions of smart contracts with constant updates in ClickHouse. Not worth rehashing here; the gist is that we'd skipped the obvious GROUP BY / FINAL approach entirely.
I recently tested whether Claude would arrive at the same solution if walked through the same reasoning we used. It did not.
Three patterns showed up clearly.
- By default, agents write what runs, not what runs well.They reach for GROUP BY, FINAL, JOINs, the obvious shape. Performance has to be asked for explicitly. If you don't, you get something that passes tests and burns CPU.
- When you push back, they optimize the current path, not the premise.Point at a problem in the solution and the agent will tune the solution. It won't step back and ask whether the operation needs to exist. In my session Claude defended its GROUP BY instead of asking whether to remove it.
- If it hasn't been written about, it won't be invented.Agents orbit canonical patterns. Anything genuinely novel, a trick sitting at the intersection of a fresh feature and a non-standard use, they won't find on their own.
My main limitation. I can apply known patterns to a new task, but inventing a new pattern at the intersection of a fresh feature and a non-standard use — that happens less often than I'd like.
— Claude, asked why it hadn't reached our solution
Keep your own head in the loop. Anything where the optimal solution sits off the well-trodden path (query design over weird data shapes, novel concurrency, cryptographic protocol tweaks, performance work on systems that don't fit the standard advice), the agent will give you something that works, not something that's good. Catching the difference is on you.
The environment leaders build
What lives next to the code, how it's organized, the script-first rule, and the old fundamentals that still hold the whole thing together. This is the layout I run at Hexens and Trenda. Two teams, both under a hundred people, both with engineering cultures that move. On 500-person enterprise legacy with regulated compliance lanes the same principles hold but the calendar stretches and the political surface changes — that's a different document.
Three repo types hold the whole transformation
Each has a specific job and a specific consumer. Together they're the substrate AI runs on. This is what leaders actually build.
feature-id runs through all three repos. Pick it up in product-docs, find it in skills, see it land in service repos.
What lives in every code repo
One repo per service: backend, frontend, mobile, infra. The substrate the agent actually operates in. Each one has the same shape, so the agent doesn't relearn the layout when it switches.
<service-name>/
├── AGENTS.md # rules for the agent: what's allowed,
│ # what's forbidden, what to verify
│ # before merge. Points to the platform
│ # skill — agent follows links from there
│ # when it needs more.
│ # → skill: <stack>-platform
├── docs/
│ ├── README.md # service overview: purpose, owners,
│ │ # how to run, dependencies
│ └── features/ # local feature notes owned here
├── src/
└── tests/AGENTS.md is the entry point: a thin pointer to the platform skill. The skill itself links onward to code-style, conventions, lib references; the agent follows those links only when it needs the details. Change a convention once in the platform skill, every service repo picks it up. docs/ is for things that belong only to this service; cross-service stuff lives in product-docs.
The platform that turns intent into delivery
The central artifact of the transformation. Skills are how a human asks for something. Agents are the heavy-lifters behind them. Between them sits MCP. Inside every agent: a pile of scripts doing roughly ninety percent of the actual work.
ai-platform/
├── skills/ # entry points humans invoke
│ ├── new-task/ # PM / analyst → new task
│ ├── be-task/ # backend engineer → implementation
│ ├── fe-task/ # frontend engineer → implementation
│ ├── review/ # PR review
│ ├── test/ # test generation and runs
│ ├── deploy-stg/ # staging deploy
│ └── release/ # prod release
│
├── agents/ # the actual workers,
│ │ # skills talk to them over MCP
│ ├── product-review/ # ↔ new-task
│ │ ├── README.md
│ │ └── scripts/ # ~90% of the agent's work
│ ├── developer/ # ↔ be-task, fe-task
│ │ └── scripts/
│ └── review/ # ↔ review
│ └── scripts/
│
└── mcp/ # MCP servers wiring skills and agentsA skill is the interface ("new task," "do a review"). An agent is the executor. MCP is the protocol between them. Inside the agent: scripts, not prompts, for everything deterministic. The agent picks the script, runs it, brings back results. This is what keeps the system stable and cheap.
Concrete example from how we run it: new-task doesn't just write the PRD. It also evaluates whether the task is simple enough to be done end-to-end by an agent. If yes, the Jira ticket is created with an agent label, and the developer-agent picks it up automatically. Most simple fixes ship without a human touching the implementation. See Script-first below for why this matters.
PM → skill:new-task → agent:product-review
↓
scripts: read PRD template, scan codebase,
find related features, draft questions
↓
back to PM: clarifying questions
↓
PM answers → agent commits PRD into
product-docs/features/<id>/prd.md
↓
ticket created in the trackerSample flow for the new-task skill. Without scripts this is an open-ended chat; with scripts it's a deterministic path.
The shared knowledge layer
One repo per product, named <product>-docs. Source of truth that both humans and agents read. The thing Confluence used to pretend to be.
<product>-docs/
├── README.md # product map: what it is, owners, slack
│
├── architecture/
│ ├── overview.md # high-level picture
│ ├── services/ # one card per service
│ │ └── <service-name>.md
│ ├── flows/ # end-to-end scenarios
│ └── adr/ # architectural decisions
│ └── 0001-<title>.md
│
├── features/
│ └── <feature-id>/ # one folder per feature,
│ │ # named after the tracker ID
│ ├── prd.md
│ ├── architecture.md # what we're building, how
│ ├── tests.md # acceptance / e2e scenarios
│ └── decisions.md # branches taken and why
│
├── tests/
│ └── e2e/ # cross-service tests live here
│
└── glossary.md # product-specific terms<feature-id> is the spine. The same ID lives in the tracker, in branch names across every service repo, and in this folder. When the agent picks up HEX-1234, it reads features/HEX-1234/prd.md and walks straight to the right branch in each service repo. No manual context-stitching.
Don't make the agent do what a script could do
The rule that quietly decides whether your environment stays stable, fast, and affordable. Or doesn't.
The rule: anything a deterministic script can do, do with a script. Checks, lookups, transformations, fan-outs, verifications. The agent gets called for what scripts can't cover: judgment, ambiguous interpretation, multi-step reasoning across unfamiliar territory. I've argued this before from the stability angle (scripts don't hallucinate; agents do). Anthropic published a piece in 2025 that lands in the same place from a different angle: tokens. The numbers there are the part worth staring at.
When an agent is wired to a dozen MCP servers, every tool description loads into context up front. That's hundreds of thousands of tokens before the agent has seen your request. It gets worse mid-task: every intermediate result flows through the model too. Ask the agent to pull a transcript from Google Drive and drop it in Salesforce, and the entire transcript travels through context twice. Just to move from one place to another.
Their fix is the same one: let the agent write a script that hits the tools in one pass, filters at the call site, and returns only what's needed. Their before/after:
Same task, scripted vs not. The exact numbers vary; the order of magnitude doesn't.
So script-first isn't only about stability. It's stability plus speed plus cost. Every step you push into code is one fewer step the model has to guess at, and one fewer pile of tokens shuttled around for no reason.
The JetBrains Air team made this concrete in their agentization cookbook. The entire verification path lives in a single script, verify.sh. One run, every check that doesn't need a model: lint, types, tests, build. Next to it, Task Briefs in docs/agent/tasks/<id>.md: scope, acceptance criteria, verification plan, written before the agent starts. If you're already using something like superpowers, that part comes for free. They also wire in stop conditions: agent escalates on changes to auth, on a DB schema change, on a 500-line diff.
That's one shape of it. Every team will pick a different one. The point isn't the directory layout. The point is that the agent should never be guessing whether a PR is mergeable. There should be a script that answers.
The boring stuff still wins
Old-but-gold practices every team used a decade ago, and somehow stopped doing once AI was writing the code.
There's a moment that keeps showing up on products I've built from scratch with an agent doing most of the heavy lifting. The agent gets stuck in a loop trying to find a bug. Tries one fix, tries another, hits the same wall. Eventually I give up and read the code myself.
The reason usually isn't the agent. The product has no logs. No request IDs. No audit trail of who did what. No idea what state the database was in when the request came in. The agent is trying to reason about a black box, and the black box wins.
Anything your team relied on before AI is still load-bearing after AI. Logs, request IDs, action trails, feature flags, traces. The boring fundamentals. Think about what would have helped you last time you were debugging at 2am, put it in, then tell the agent it's there. The new tools amplify the system; they don't replace its foundations.
How the team moves day to day
How a team in this environment actually works through a week. Two pieces: the rituals that keep principles from drifting, and the fourth step nobody talks about that makes the environment compound.
Five things that became ritual
None of these depend on tools alone. Each exists to stop a principle from quietly slipping back to the old way.
- Kanban inside the quarterFlow instead of sprints. Quarterly planning stays for big bets and direction; within the quarter you ship when a feature is ready, not when the sprint clock ticks.
- Every engineer is a feature ownerFrom PRD to production, through every service the feature touches. You hire for ownership, not for stack proficiency. Stack is learnable in weeks; ownership is a disposition.
- Research time is work time, sharing is mandatoryTime spent learning AI tools, reading Anthropic docs, or trying open-source skills is allocated, not stolen from evenings. The Friday demo (thirty minutes, what worked and what didn't) is where the loop closes. Research that doesn't return to the team is invisible.
- Automate the small things firstAI makes it cheap to script the boring stuff: PR labels, release notes, on-call summaries, dependency bumps. Those are the places that burn out senior people, and the first thing a team should touch in week one.
- AI code review before human reviewFirst pass by an agent following the review skill. Humans review the cleaned PR, spending cycles on architecture and intent, not on style and trivial mistakes.
The fourth mandatory step
After a hard task, especially after a particularly ugly bug, I ask the agent to write the whole thing up properly. What we actually did. What wasn't obvious. Why the bug appeared in the first place. How not to make the same mistake next time.
What you end up with after a well-solved problem is not just code. It's the understanding of how you got there. That's an artifact too.
The classic dev loop is plan → implement → review. There's a fourth step worth treating as mandatory, often called compound engineering: after the task is done, write up what was learned so the system gets it next time.
The effect doesn't show up immediately. But over time, after every task, the environment around the team gets better. Quietly, without anyone having to set a quarterly objective for "improving the environment":
- the solution is saved next to the code, not in someone's head;
- what worked and what didn't is recorded;
- reusable conclusions are extracted into the platform skill;
- internal rules and patterns for agents get updated;
- checks are added so the same class of bug gets caught automatically.
Every hard task ends up improving both the product and the system that builds it. This is what makes the environment compound instead of decay.
You don't add metrics. You change which questions you're asking.
Adopting AI changes which numbers carry signal. None of the obvious ones (LOC per day, PRs per day) are on the list. Three views worth watching instead.
Is the environment actually getting better?
These tell you compound engineering is working, or that it has become a ritual nobody believes in. The first one is the killer: it's the compound thesis made measurable.
- Postmortems that closed into a skill updateOf every postmortem, what fraction resulted in a committed change to a skill or a new automated check. Under half means the compound step is leaking. You wrote the doc but never moved the learning back into the system.
- Lead time per featureFrom PRD committed to feature live in prod. If it drops quarter over quarter, the system is compounding. If it's flat, compound is theatre.
- Bug recurrence rateHow often a class of bug shows up again after a postmortem said it wouldn't. Near-zero means postmortems are reaching skills. Anything else means the update didn't happen.
- Time-to-productive for a new juniorDays from start to first shipped feature. In a mature environment this is weeks, not months. The platform skill teaches the agent what would have taken three pairing sessions.
Is the agent's output actually good?
The view most teams skip, and the place most adoptions quietly fail. These tell you whether the platform skill is doing real work or just sitting in a folder.
- Bug rate: AI-authored vs human-authoredIf AI-authored code has more incidents than human, your skills aren't carrying enough conventions. If the rates are roughly equal or AI wins, the platform is doing its job.
- Review iterations to mergeHow many rounds of comments before a PR is mergeable. The AI review pass should bring this down to one human round on average. Multiple human rounds means the review skill needs work.
What you stop tracking, what you start
Adopting AI changes which numbers mean anything. Some old metrics quietly stop carrying signal. New ones become the ones you check on Monday.
- Stop: LOC per day, PRs per dayThese were proxies for individual output. AI broke them. A senior writing one PR a week with deep architectural impact looks weak on these dashboards. Stop using them.
- Start: time-to-first-PR for new hiresHow fast someone gets from accepted offer to merged code. The faster this gets, the better the environment is at onboarding humans, not just agents.
- Start: cycle time on cross-functional decisionsFrom a question asked by product to an answer landed in the PRD. Short means the loop between PM-via-agent and engineering is tight. Long means something in the chain still needs a human translator.
What changes in the org
Structural shifts that emerge as a consequence of the first three sections. Downstream effects, not separate initiatives — what we see emerging at our scale, not a settled industry norm. The repo and skill layout in §04 has been run; what follows is direction the rest of the work has been pointing at.
- Value shifts from individual output to environment-buildingIf all you do is use Claude or Cursor to ship faster, you're now competing with a hundred others doing the same. The bar to "ship something quickly" is dropping fast. The people whose impact grows are the ones building the processes, setting the rules that keep things safe and scalable, and creating the environment everyone else delivers in. Everything below is downstream of this.
- Big departments fragmentThirty people becomes three teams of ten. Each team is self-contained: product, backend, frontend, QA capability inside it. Fewer hand-offs, faster decisions.
- Ownership is valued at every level, juniors includedCarrying a result is the entry point to the system, not a privilege of seniority. A junior who can deliver a small feature end-to-end (with AI as a force multiplier) moves faster than a mid who can't.
- PMs write PRDs through a skillThe PM has no repo access; the agent does. PM prompts, the agent commits the PRD to product-docs/features/{feature-id}/prd.md. PMs are part of the engineering loop without becoming engineers.
Three phases from Launch to Maturity
Each phase is defined by what exists from the repo, process, and team-shape sections at its end, not by re-describing principles. Phases are an order, not a calendar; each has to finish before the next begins.
Fear is gone, skills start to live
→ Remove the fear of doing it wrong. Let the team play. Get the first skills in.
Service repos
- AGENTS.md in the primary repos.
- Sandboxes per branch for the pilots.
Skills/MCP/Agent repo
- First skills committed to a shared repo. Rough, not idealized, but versioned.
- ai-learnings repo so first findings don't dissolve in Slack.
Process
- Claude Code rolled out to everyone: dev, QA, product, analytics, frontend.
- Weekly AI demo running. Allocated research time on the calendar.
- Frontend tried Figma Make / Claude Design. PMs vibe-coded a pet project to feel the limits.
Team shape
- Nothing structural yet. Phase 1 is about removing fear, not redrawing the org.
AI is a tool — now make it a lever
→ Context discipline, skills as system, product-docs in place. Lead time being measured.
Service repos
- Single branch name per feature across repos.
- Postmortems update skills, so incidents stop repeating through agents.
Skills/MCP/Agent repo
- Skills per stack committed (backend, frontend, mobile, QA), versioned and reviewed.
- A legacy skill for predictable refactoring.
Product repos
- First <product>-docs repo with architecture/, features/<feature-id>/, tests/.
- Architecture of existing services committed in architecture/.
- A PRD template AI can fill cleanly (Context / User stories / Acceptance / Edge cases / Out of scope).
Process
- Context discipline is a team norm: people stop saying "write a function" and start saying "write this with these constraints."
- AI code review before human review.
- Lead time being measured. Baseline for the kanban transition.
Team shape
- PMs and analysts inside the AI loop; analysts draft PRDs from meeting recordings.
- Quarterly planning kept; sprints on their way out.
Roles dissolve. A feature walks from idea to prod with the team mostly watching.
→ Automated what can be. Skills turned each person into a generalist. Roles blur. This is a North Star, not a six-month plan. Most teams will live somewhere between phases 2 and 3 indefinitely, and that's fine.
Service repos
- Every active repo carries an up-to-date AGENTS.md.
Skills/MCP/Agent repo
- Skills cover every stack and every cross-cutting concern (review, legacy refactor, PRD authoring, UI design system), all written script-first by default.
Product repos
- Legacy fully documented in product-docs (agent reads, developer validates).
- Every feature has a complete features/<feature-id>/ folder.
Process
- Kanban inside the quarter. Releases independent of planning. Feature ready, feature ships.
- Each quarter you commit a bit more than the last. The bar moves.
Team shape
- Every engineer is a feature owner end-to-end.
- Tech leads become Lead Engineers: final say in their stack but still delivering features themselves.
- PMs commit PRDs through a skill, no repo access required.
- Simple features start with PM-via-agent and arrive as a PR for engineer review.
- Role boundaries dissolve: product reads code, engineers write product, analysts do both.
What can go wrong
Nine traps. None obvious until you're inside.
- 01
Speed vs stability
Going forward too fast and losing product stability. Each phase has to finish before the next one starts. Not in the calendar, but in reality on the ground.
- 02
The senior who won't adapt
Not the team-wide fear. The specific case: your strongest IC who's earned the right to push back, and quietly does. They keep working the way they always worked. Within a year they're the slowest person on the team because everyone else compounded and they didn't. The leader has to name this directly: opting out is opting down, not staying still.
- 03
"What am I needed for now"
Engineers can read AI as a threat instead of an amplifier. The leader must say it explicitly: you're paid for ownership and judgment, not for lines of code per day.
- 04
Fear of role cuts
The team becomes smaller and stronger. Frame it honestly: optimization is a win and a strong resume line. Being a year behind is the actual minus.
- 05
Tech debt accelerating
AI can write good code, but only if told how. Without the right skills and reviews you get code that runs but is sloppy. Weak mids won't catch this. They'll ship it, and the bill arrives in six months.
- 06
AI-generated entropy
AI ships code faster than humans can review it. The review skill and the human pass close part of the gap, not all of it — reviewers can't keep up with several agents running in parallel branches. This is structural, not a story about weak engineers. The countermeasure is a capacity cap, not more discipline: limit concurrent feature branches per engineer, schedule integration-debt weeks every N releases, refuse merges whose context a reviewer can't reconstruct from the docs. Without a cap, entropy compounds silently and only surfaces when something breaks across three features at once.
- 07
Cost compounding
Script-first discipline is the only thing standing between a controlled AI bill and a runaway one. Measure token spend per merged PR, not per developer. The per-developer number flatters everyone and tells you nothing about leverage. If per-PR spend trends up while lead time stays flat, you're paying for theater.
- 08
Vendor lock-in
The framework here is built on Claude Code conventions: AGENTS.md, the skills format, the agent tooling around them. A migration to another agent is possible but not free — context files, skill prompts, and the orchestration layer all need rewriting. The realistic position is single-vendor today, multi-vendor in twelve to eighteen months once agent-format conventions stabilize across providers. Locking in is a deliberate trade. Don't pretend it isn't a trade.
- 09
Model churn
Every model release can quietly change how a skill behaves. A skill that produced clean PRD scaffolds last quarter can start drifting after a model bump, and you won't notice until a PRD ships wrong. The mitigation is a smoke-test suite per skill: a small set of fixed inputs whose outputs you check by hand on every model version change. Without it, "it worked yesterday" becomes a quietly accumulating class of bugs.
If any of this lands for your team, or breaks in interesting ways, I'm at @stayhightech on Telegram. I take counter-examples seriously.
A working document. Next version covers security. Current — v0.4, updated 2026-05-25.