Repo-Native AI Architecture: 5 Ways to Build and Run AI Agents
Repo-Native AI Architecture: 5 Ways to Build and Run AI Agents
From Markdown files to microservices — choosing the right architecture for the job
By Mark Kendall | Repogenic | Intent-Driven Engineering
We’ve spent years building applications around frameworks, services, APIs, containers, and increasingly complex infrastructure.
Now AI agents are changing how we approach software engineering.
But there’s an important architectural lesson emerging:
Not every AI agent needs to be a microservice. Not every agent needs a framework. And not every agent needs its own infrastructure.
Sometimes an agent is a Markdown file.
Sometimes it’s a Python script.
Sometimes it runs automatically when a developer creates a pull request.
And sometimes it really does need to be an enterprise service.
The trick is understanding the difference.
At Repogenic, we’re exploring what I call Repo-Native AI Architecture: building AI capabilities around the repository, its context, its engineering standards, and the intent of the people developing the software.
Let’s explore five practical ways to implement AI agents, with working concepts and lightweight examples.
1. Markdown Agents: The Simplest Starting Point
Architecture: Agent Definition + Existing Runtime
One of the most interesting developments in agent engineering is how little code is sometimes required.
With tools such as Claude Code, you can define a specialized agent using a Markdown file.
The file describes the agent’s responsibilities, tools, constraints, and expected behavior.
The execution engine already exists.
You provide the instructions.
Example: Code Review Agent
Repository structure:
my-repository/
│
├── .claude/
│ └── agents/
│ └── code-reviewer.md
│
├── src/
│ └── application.py
│
└── README.md
Inside code-reviewer.md:
---
name: code-reviewer
description: Reviews code for quality,
security, and maintainability.
tools: Read, Grep, Glob
---
# Code Review Agent
Your responsibility is to review
repository code.
## Objectives
- Identify potential defects.
- Detect security vulnerabilities.
- Evaluate maintainability.
- Recommend improvements.
## Constraints
- Do not modify source code.
- Do not invent findings.
- Report only evidence-supported issues.
## Output
For each issue, provide:
- File and line reference
- Severity
- Description
- Recommended correction
If no issues are found, report:
"No actionable issues identified."
That’s an agent definition.
Claude Code can discover this agent and delegate an appropriate review task to it.
The runtime handles the model interaction, context management, and authorized tool execution.
Why this matters
Developers don’t have to write their own orchestration framework just to create a specialized reviewer.
They can reuse the capabilities of an existing agent runtime.
Best for: Code reviews, documentation, repository analysis, test evaluation, and specialized engineering tasks.
Repogenic principle: Define the intent. Reuse the runtime.
2. Script-Based Agents: Lightweight AI Automation
Architecture: Script + Model + Tools
Sometimes a Markdown definition isn’t enough.
You need custom logic.
Maybe you want to inspect a directory, compare configuration files, analyze test results, or produce a structured report.
A Python or JavaScript script can coordinate these operations.
Here’s a simple Python example using Anthropic’s SDK.
Example: Python Code Analyzer
import os
from pathlib import Path
from anthropic import Anthropic
client = Anthropic()
def review_file(filename):
code = Path(filename).read_text()
response = client.messages.create(
model=os.environ["CLAUDE_MODEL"],
max_tokens=1000,
messages=[
{
"role": "user",
"content": (
"Review this Python code for "
"bugs and security issues.\n\n"
+ code
)
}
]
)
for block in response.content:
if block.type == "text":
print(block.text)
review_file("src/application.py")
Install the dependency:
pip install anthropic
Configure your API credentials and a supported model identifier through environment variables.
This example performs a single model-based analysis. Strictly speaking, it’s an LLM-powered automation rather than a fully autonomous agent.
But it demonstrates the foundation.
By adding a controlled tool-use loop, the script can inspect additional files, select approved tools, and make decisions based on intermediate results.
You can also use an existing agent SDK rather than writing that loop yourself.
Why this matters
The execution environment can be almost anything:
A developer’s workstation
A GitHub Actions runner
A scheduled job
A serverless function
An existing application
No Kubernetes cluster required.
Best for: Targeted automation, repository utilities, lightweight analysis, and scheduled AI tasks.
Repogenic principle: Complexity must earn its existence.
3. CI/CD Agents: Event-Driven AI Engineering
Architecture: Repository Event + Workflow + Agent Runtime
This is where things get especially interesting.
Imagine creating a pull request and having an AI agent automatically examine the proposed changes.
The agent knows the repository.
It understands the engineering standards.
It reviews the code against the expected intent.
And it reports its findings directly in the development workflow.
No developer needs to remember to start it.
The repository event triggers the process.
Example: GitHub Actions PR Reviewer
Create:
.github/workflows/pr-review.yml
Add a workflow:
name: AI PR Review
on:
pull_request:
types: [opened, synchronize, reopened]
permissions:
contents: read
pull-requests: write
issues: write
id-token: write
jobs:
review:
runs-on: ubuntu-latest
steps:
- name: Checkout Repository
uses: actions/checkout@v4
- name: Run AI Reviewer
uses: anthropics/claude-code-action@v1
with:
anthropic_api_key: >-
${{ secrets.ANTHROPIC_API_KEY }}
prompt: |
Review this pull request.
Examine the changed files.
Identify significant bugs,
security risks, and
maintainability problems.
Provide evidence for
every finding.
Do not modify the code.
This is a simplified example based on the Claude Code GitHub Action. Actual deployment requires the action’s authentication and GitHub integration setup, and repository permissions should be reduced to the minimum needed.
Notice what happened.
GitHub Actions handles the trigger.
The workflow launches Claude Code.
Claude examines the repository and pull request using its available capabilities.
The results can be published back to GitHub.
And there’s another possibility.
The workflow can instruct Claude Code to delegate the review to a specialized agent defined in:
.claude/agents/code-reviewer.md
Now we have separated three responsibilities:
Workflow: When should the review run?
Agent: What work needs to be performed?
Runtime: How does the work get executed?
That separation is extremely valuable.
Why this matters
CI/CD is no longer limited to executing deterministic build scripts.
It can also coordinate AI-assisted engineering tasks.
But AI reviews should complement deterministic tests, security scanners, and branch protections—not replace them.
Best for: Pull request reviews, documentation checks, release analysis, repository compliance, and engineering quality assessments.
Repogenic principle: Let the repository trigger the intelligence.
4. SDK-Based Agents: Custom Agent Applications
Architecture: Application + Agent SDK + Tools
Eventually, you may need more control over agent behavior.
Perhaps the agent must coordinate multiple tools, manage specialized contexts, or participate in a larger application.
That’s where an agent SDK becomes useful.
An SDK provides programmatic access to agent capabilities while allowing developers to control the application around them.
Example: Python Agent SDK
Using the Claude Agent SDK:
import anyio
from claude_agent_sdk import (
query,
ClaudeAgentOptions
)
async def main():
options = ClaudeAgentOptions(
allowed_tools=[
"Read",
"Glob",
"Grep"
],
max_turns=5
)
async for message in query(
prompt=(
"Analyze this repository "
"for maintainability risks. "
"Do not modify files."
),
options=options
):
print(message)
anyio.run(main)
The SDK provides an agent execution interface.
The application decides how to invoke it.
The agent can use permitted tools to explore repository context and complete the delegated analysis.
The allowed tools and execution permissions should be explicitly configured for the environment.
This opens the door to larger systems involving specialized agents, structured results, and tool orchestration.
For example:
Repository
|
v
Architecture Agent
|
v
Security Agent
|
v
Testing Agent
|
v
Consolidated Findings
Each agent can have a specialized responsibility without requiring a separately deployed service.
Why this matters
An SDK-based approach provides flexibility while avoiding the cost of building an entire execution framework from scratch.
Best for: Custom AI applications, multi-agent coordination, specialized orchestration, and complex engineering workflows.
Repogenic principle: Build custom orchestration only when the requirements justify it.
5. Microservice Agents: Enterprise AI Capabilities
Architecture: API + Agent Service + Runtime
Sometimes a dedicated service is exactly what you need.
Imagine an AI capability consumed by several applications, business units, or development teams.
It may require centralized authentication, durable execution, independent scaling, audit logging, and governed access to enterprise systems.
A microservice can provide those capabilities.
Example: Python Agent API
Using FastAPI and Anthropic:
import os
from fastapi import FastAPI
from pydantic import BaseModel
from anthropic import Anthropic
app = FastAPI()
client = Anthropic()
class ReviewRequest(BaseModel):
code: str
@app.post("/review")
def review(request: ReviewRequest):
response = client.messages.create(
model=os.environ["CLAUDE_MODEL"],
max_tokens=1000,
messages=[
{
"role": "user",
"content": (
"Review this code for "
"defects and security risks:\n\n"
+ request.code
)
}
]
)
findings = "\n".join(
block.text
for block in response.content
if block.type == "text"
)
return {"findings": findings}
Run the service:
pip install fastapi uvicorn anthropic
uvicorn app:app
Now another system can submit code for analysis through an API.
This example demonstrates service packaging around a single LLM request, not a complete autonomous agent. A production agent service would add the appropriate agent runtime and tool orchestration.
A production implementation would also require authentication, authorization, request limits, observability, secrets management, and other security controls.
Why this matters
Microservices make sense when AI capabilities must operate as governed, shared enterprise resources.
But deploying a microservice simply because something is called an agent introduces unnecessary operational complexity.
Best for: Enterprise AI platforms, shared agent capabilities, centrally governed workflows, and independently scaled services.
Repogenic principle: Architecture should follow operational requirements, not terminology.
The Bigger Picture: Repo-Native AI Architecture
Now consider what these five approaches have in common.
Every implementation needs some combination of:
Intent: What outcome should the agent accomplish?
Context: What information does the agent need?
Capabilities: Which tools and skills can it use?
Execution: What runtime performs the work?
Governance: What boundaries must it respect?
Evidence: How do we know the work succeeded?
These are the foundational concerns of Repo-Native AI Architecture.
The repository becomes more than a collection of source files.
It can contain the engineering intent, reusable capabilities, agent definitions, execution workflows, and evidence required to validate results.
Consider this conceptual repository structure:
repogenic/
│
├── intent/
│ └── PR-REVIEW.md
│
├── .claude/
│ ├── agents/
│ │ └── pr-reviewer.md
│ │
│ └── skills/
│ └── code-review/
│ └── SKILL.md
│
├── .github/
│ └── workflows/
│ └── pr-review.yml
│
├── src/
│ └── application-code/
│
└── tests/
Everything has a responsibility.
The intent defines the desired outcome.
The agent owns the delegated task.
The skill provides reusable knowledge or procedures.
The GitHub workflow handles execution triggers.
The runtime performs the authorized work.
The tests and review results provide evidence.
That’s a powerful architectural pattern without requiring an elaborate platform.
Where Do Marketplaces and Plugins Fit?
There’s another important architectural consideration.
How do we distribute these capabilities across development teams?
This is where plugins and marketplaces become useful.
A centralized engineering team can maintain reusable agent definitions, skills, and supporting resources.
Development teams can install approved packages into compatible runtimes.
For example:
Central Agent Marketplace
|
v
Engineering Plugin
|
+-- PR Reviewer Agent
|
+-- Security Review Skill
|
+-- Test Analysis Skill
|
+-- Engineering Standards
|
v
Development Repositories
|
v
Agent Runtime / CI Pipeline
|
v
Review Results
A marketplace distributes capabilities.
A plugin packages them.
An agent runtime executes them.
A workflow determines when they execute.
These are different architectural responsibilities.
Importantly, distribution is not the same as governance. Enterprises still need to control which capabilities are approved, what permissions they receive, and how their execution is audited.
A shared-services team can begin with a small number of useful skills and agents, demonstrate their value, and expand adoption based on evidence.
It doesn’t need to build an enormous platform on day one.
Intent-Driven Engineering: The Missing Connection
At Repogenic, we believe an AI agent should begin with intent, not implementation.
Before deciding whether to use Markdown, Python, an SDK, GitHub Actions, or Kubernetes, we should answer four questions:
1. Intent: What are we trying to accomplish?
2. Inputs and Context: What information is required?
3. Outputs: What should the agent produce?
4. Success Criteria: What evidence proves the outcome is acceptable?
For example, consider a PR reviewer.
Its intent might be:
Review proposed repository changes and identify significant defects, security risks, and violations of engineering standards before code is merged.
Its constraints might include:
Review only the intended changes and relevant surrounding context.
Do not modify application code.
Reference evidence for every finding.
Distinguish actual defects from speculative concerns.
Report when no actionable issues are identified.
Never approve or merge a pull request automatically.
Notice that we haven’t specified Python, Claude Code, an SDK, or Kubernetes.
We’ve defined the outcome.
Now we can select the most appropriate execution architecture.
That’s Intent-Driven Engineering.
Our Next Experiment: The Repogenic PR Reviewer
We’re going to demonstrate this architecture in our own repository.
The first implementation will be deliberately simple.
We’ll create a repository-native PR reviewer using a Markdown agent definition and GitHub Actions.
Our initial objectives are straightforward:
First: Define the review intent.
Second: Create the PR reviewer agent.
Third: Connect the agent to an appropriate GitHub Actions workflow.
Fourth: Open a test pull request containing Python or JavaScript changes.
Fifth: Evaluate the review findings against actual code evidence.
The important measurement isn’t how many agents we created.
It’s whether the review produces useful, accurate, actionable results.
A successful review with no findings is a valid outcome.
A confidently reported false positive is not.
We’ll also measure execution time, cost, and repeatability so the implementation can evolve based on evidence.
If the lightweight approach works, we keep it.
If future requirements justify more sophisticated orchestration, we can introduce it.
But we won’t build unnecessary infrastructure just because we can.
Final Thought: Start With the Repository
The future of AI engineering isn’t simply about building more agents.
It’s about building the right capabilities, placing them in the right execution environments, and connecting them to clear human intent.
Sometimes the right architecture is a Markdown file.
Sometimes it’s a script.
Sometimes it’s GitHub Actions.
Sometimes it’s an SDK.
And sometimes it’s a microservice.
These patterns aren’t mutually exclusive. A Markdown-defined agent can run through an SDK inside a GitHub Actions workflow, and that same workflow can call a remote agent service.
They’re complementary building blocks.
The engineering challenge is choosing the simplest combination that satisfies the requirements.
Repo-Native AI Architecture puts intent, context, execution, and evidence close to the software being developed.
And that’s the direction we’re exploring at Repogenic.
Start with intent. Stay close to the repository. Reuse what works. Let complexity earn its existence.
Repogenic — Intent-Driven Engineering and Repo-Native AI Architecture.
Technical references
The examples align with Anthropic’s current documentation for Claude Code subagents, the Claude Agent SDK for Python, and the Claude Code GitHub Action. GitHub’s workflow security and permissions documentation is also important before enabling automated reviews.
What I’d build next for Repogenic
I’d start with one Markdown agent and one GitHub Actions workflow, rather than five separate implementations.
The first version would have three files:
repogenic/
├── intent/
│ └── PR-REVIEW.md
├── .claude/
│ └── agents/
│ └── pr-reviewer.md
└── .github/
└── workflows/
└── pr-review.yml
We can make the reviewer examine Python, JavaScript, and configuration changes, report evidence-backed findings, and leave your code untouched.
I’d also make the first version manual-triggered before enabling automatic PR reviews. That gives us a chance to validate the results and API costs without triggering unnecessary executions.
Then we can turn it into a real example of Repogenic’s architecture: intent → agent → runtime → evidence → improvement.
That’s a better demonstration than creating another elaborate agent framework.
Comments