Every time I started a new AI session, I found myself doing the same thing: re-explaining the project, re-describing the architecture, re-telling the AI what we were working on. Sometimes it would take 10–15 minutes just to get the AI to the point where it could actually help. And the next day? Same thing. Start over.
I was using Claude Code and Windsurf heavily on the CWAN API Service project, our API gateway platform here at Clearwater Analytics. Over 18 months of daily iteration on a production platform with 1,200+ API endpoints, our team built something that worked really well. The AI knew the codebase. It knew the architecture. It picked up where we left off every single session. The workspace grew to 93 workflows, 14 specialized agents, and 79 slash commands, and the team was genuinely operating at a different level than teams that were just using “AI chat.”
The question I kept asking myself was what exactly made it work? And could I package that so any team, on any codebase, could have the same thing?
That question led to the Agentic-Repos framework.
A standard repository contains code. An agentic repository contains code plus a complete AI knowledge layer. The difference is significant.
The way I describe it, a standard repo is an empty apartment. The walls are the same, the plumbing is the same, but one is ready to live in. An agentic repository is furnished. When you open it in Claude Code or Windsurf, the AI already knows:
It does not ask you to explain the project. It does not start from scratch. It picks up where you left off.
The way this works is not magic. It is a set of files that load automatically when the AI session starts, a structured knowledge base it can navigate efficiently, and specialized agents tailored to the specific tech stack.
After 18 months of running this in production, I distilled the approach into six principles. Every one of them is non-negotiable.
The reason these work together is that they address the three biggest failure modes I kept seeing in teams using AI for development. The AI makes things up, the AI repeats itself because it has no memory, and the AI produces content that nobody can find or trust.
Here is what the AI knowledge layer looks like inside a repository after you run the conversion:
Each piece solves a specific problem:
CLAUDE.md loads automatically when you open the project in Claude Code. It tells the AI the rules it must follow, the commands available, and the structure of the project. This is not a generic set of instructions. It is tailored to the detected tech stack. AGENTS.md does the same for Claude Code’s workspace context.
START_HERE.md is what the AI reads at the beginning of every session. It contains the current project context, what the team is working on, and the priorities. This is the file that eliminates the “let me understand your project” conversation that wastes the first 10 minutes of every AI session.
The Knowledge Graph is the piece most people overlook, and it is the piece that makes the biggest difference. Instead of the AI searching blindly through files, it uses a structured graph with authority tiers, concept clusters, and a search index. Tier 1 is Source of Truth — documents that only humans can modify. When two documents conflict, the higher tier wins.
The Generated/ directory keeps AI output separate from human-authored knowledge. This seems like a small detail, but it is critical for trust. If everything in Knowledge/Source of Truth/ was verified by a human, and everything in Generated/ was produced by AI, you always know what to trust.
The reason I built this as a framework rather than just documenting the CWAN API Service setup is that I wanted any team to be able to apply it to any codebase. The result is a single command:
You provide a repository URL or a local path. The framework:
The entire thing is evidence-based. Nothing is invented. The agent reads actual files before making any claim about the repo. If you use Windsurf instead of Claude Code, the equivalent /convert-repo-to-agentic workflow is included as well.
One thing I spent real time on was making the tech stack detection reliable. The agent does not assume. It runs detection commands:
# Framework detection
grep -rl “springframework” src/ –include=“*.java” –include=“*.kt”
grep -rl “fastapi\|flask\|django” . –include=“*.py”
grep -rl “express\|nestjs” src/ –include=“*.ts”
Then it adapts what it generates based on what it actually finds. A Spring Boot repo gets a CLAUDE.md with Maven commands and Spring-specific patterns. A FastAPI repo gets pytest patterns and uvicorn startup commands. A Terraform repo gets HCL syntax guidance and resource patterns.
The generated agents are also adapted. A developer agent for a Spring Boot service knows about annotations, Maven lifecycle, and Spring idioms. A developer agent for a FastAPI service knows about async patterns, Pydantic models, and pytest fixtures.
I want to be specific about session continuity because this is the part that has the biggest practical impact.
In a standard AI workflow, every session starts from scratch. You explain the project, you explain what you are working on, you explain what you tried last time. This wastes time and leads to repetition.
In an agentic repo, the first thing the AI does in every session is run three reads:
The Progress Tracker is updated at the end of every session using /project:generate-session-context. It captures what was accomplished, what is in progress, what decisions were made, and what the next three priorities are. The next session starts by reading it and continuing directly.
The difference in experience is significant. Teams that use this stop re-explaining their projects to AI. They start treating AI sessions the way they treat a colleague who was in the last meeting: you do not re-introduce the project, you just continue.
This did not start as a framework. It started as a messy collection of markdown files in one repository.
The CWAN API Service workspace that this framework was extracted from now has:
The measurable impact was that new developer onboarding dropped from weeks to about a day. An engineer joins the team, opens the repository, and the AI agent walks them through the architecture, the current priorities, and the conventions. The knowledge is in the graph, not in someone’s head.
When I say the framework produces specialized agents, I do not mean agents with different names that do the same thing. I mean agents with fundamentally different initialization sequences, different knowledge loaded, and different operational modes. Here are three from the CWAN API Service that illustrate the range.
This agent acts as an AI-powered scrum master. When activated, it does not ask “what sprint are you on?” It runs a sequence: it reads the project onboarding file, loads the Knowledge Graph, pulls the latest state of the API gateway to count how many services are onboarded (a key metric the team tracks against a quarterly scorecard), then syncs the current sprint from the project management system. It compares the live ticket statuses against the last known state and only updates files if something changed. If nothing changed, it skips the rewrite entirely and reports “no changes since last sync.”
The result is that when an engineer or a manager opens a session, the agent greets them with a context-aware summary: how many services are live, what the sprint backlog looks like, which tickets are blocked, and what the velocity trend is. The entire initialization takes a few seconds. Without this agent, assembling the same picture from the ticketing system, the deployment state, and the sprint board would take 15–20 minutes of manual navigation.
The reason this works is that the agent has explicit rules for each step: where to read credentials, what commands to run, how to detect whether the data is stale, and what format to use for the greeting. None of this is left to the AI’s judgment. The judgment is encoded in the workflow.
This is the agent I use for cross-domain reasoning across the entire platform. The CWAN API Service spans multiple service domains: security infrastructure, client management, reporting, fund accounting, and more. Each domain has its own repository, its own Knowledge Graph, and its own specialized agents. But sometimes you need to answer a question that spans domains: “If we change the authentication pattern on the gateway, which downstream services are affected?” or “What is the current integration status between our API platform and the frontend application layer?”
The domain intelligence agent loads knowledge files from multiple domains at initialization: the architecture blueprint, the verified system numbers, the integration strategy documents, and the service-level Knowledge Graphs from each domain it needs to reason about. It can trace a question from the gateway configuration through the authentication layer to the backend service and back to the frontend, citing specific documents at each step.
Without this agent, answering cross-domain questions required scheduling a meeting with engineers from each team. With it, the answer comes back in seconds, with citations to the source documents so you can verify every claim.
This is the most technically specialized of the three. It understands the API gateway infrastructure: Terraform configurations, OpenAPI specifications, Nginx routing rules, service onboarding procedures, and the Lambda-based authentication system. When activated, it reads the gateway repository’s onboarding file, loads the gateway-specific Knowledge Graph, and presents a set of demo questions showing what it can answer.
The value of this agent is in what it prevents. Before it existed, onboarding a new backend service to the API gateway required reading multiple Terraform files, understanding the routing conventions, and manually verifying that the OpenAPI spec matched the backend’s actual endpoints. An engineer unfamiliar with the gateway could spend days on their first onboarding. With the agent, the process is guided: it knows the steps, the conventions, the common mistakes, and it can generate the configuration files based on the backend service’s actual endpoints.
This is what I mean when I say the agentic repo pattern produces senior-level agents. Each of these agents has deep domain knowledge that would take a human weeks to accumulate. The knowledge is not in the AI’s training data. It is in the Knowledge Graph, the architecture documents, and the rules files that the framework creates and maintains.
The direction I am working toward is making the agentic layer a standard part of repository scaffolding, the same way a README, a .gitignore, and a CI/CD config are standard today. When you create a new repository, it should come with a Knowledge Graph, a set of AI agents tailored to the tech stack, and the rules that make those agents reliable.
The gap between teams that use AI as a chat interface and teams that build structured knowledge environments for their AI agents is already significant. It will only grow. Rolling this out across CWAN is how we make our whole SDLC smarter.
Rany ElHousieny is an Engineering Leader at Clearwater Analytics with over 30 years of experience in software development, machine learning, and artificial intelligence. He has held leadership roles at Microsoft for two decades, where he led the NLP team at Microsoft Research and Azure AI, contributing to advancements in AI technologies. At Clearwater, Rany continues to leverage his extensive background to drive innovation in AI, helping teams solve complex challenges while maintaining a collaborative approach to leadership and problem-solving.