Office Hours — What's the best way to set up an AI agent to understand my codebase and development environment without requiring screenshots and manual explanations?

What’s the best way to set up an AI agent to understand my codebase and development environment without requiring screenshots and manual explanations?

The honest answer: you need to give your agent access to structured metadata about your codebase, not just raw files. Screenshots and manual explanations don’t scale because they’re high-friction and lossy. What actually works is building an interface layer that exposes the information an agent needs to reason about your environment in a machine-readable way.

Start with what the agent actually needs to know

An agent doesn’t need to see your entire codebase. It needs to know:

How to find relevant code quickly (file structure, naming conventions, directory layout)
What key modules and libraries your project uses
Which services and APIs your infrastructure exposes
Current failing tests or error states
Architecture and design patterns you follow
Where the code lives (Git repo URL, branch conventions)
Who owns which parts of the system

You can encode all of this in a single JSON or YAML manifest that the agent reads at startup. Here’s a stripped-down example:

{
  "project": "invoice-service",
  "root_dir": "/home/dev/projects/invoice-service",
  "language": "python",
  "key_directories": {
    "api": "src/api/",
    "models": "src/models/",
    "tests": "tests/",
    "config": "config/"
  },
  "dependencies": {
    "web_framework": "FastAPI",
    "orm": "SQLAlchemy",
    "testing": "pytest"
  },
  "external_services": [
    {
      "name": "stripe_api",
      "endpoint": "https://api.stripe.com",
      "docs_url": "https://stripe.com/docs/api"
    }
  ],
  "git_config": {
    "repo": "git@github.com:myorg/invoice-service.git",
    "default_branch": "main",
    "protected_branches": ["main", "staging"]
  },
  "test_command": "pytest tests/ -v",
  "lint_command": "ruff check src/",
  "architecture_notes": "Service follows domain-driven design. Invoice aggregate in src/models/invoice.py is the core entity."
}

This is 50 lines of structured data that tells an agent more than a screenshot ever could.

Use git and your VCS as the source of truth

Rather than dumping code files into the agent’s context, let the agent query your version control system. GitHub’s API (or GitLab, or Gitea) lets you:

List files in a directory without downloading everything
Retrieve specific files on demand
Read recent commits and PRs to understand recent changes
Access blame information to know who wrote what and when

Give your agent access to a tool that fetches code on demand:

def fetch_file_from_repo(repo_path: str, file_path: str, branch: str = "main") -> str:
    """Fetch a single file from the repository."""
    # Use GitHub API or subprocess to git show
    # Return file contents
    pass

def search_files_by_pattern(pattern: str, max_results: int = 20) -> List[str]:
    """Find files matching a regex or glob pattern."""
    # Return list of matching file paths, not contents
    pass

def get_recent_commits(file_path: str, limit: int = 10) -> List[Dict]:
    """Get recent commits touching a specific file."""
    # Return commit metadata: author, message, timestamp
    pass

This way the agent can explore your codebase interactively without you having to pre-upload everything. It also stays current as your codebase changes, unlike a static snapshot.

Build a minimal “codebase map” for large projects

If your codebase is huge (millions of lines), even querying git on demand gets expensive in tokens. Create a lightweight map that documents the structure:

List of all modules and their single-line purpose
Public APIs and function signatures for each module
Config schema and environment variables
Database schema (if applicable)
Common error patterns and how to debug them

This reads like internal documentation (which it is), but it’s structured so an agent can parse and reason about it. A codebase map for a 500K-line project might be 15-20KB of plain text, not 500MB of source code.

Let the agent discover context through tool calls, not upfront

Resist the urge to cram everything into the system prompt. Instead, give the agent tools to investigate:

list_directory(path) — show what’s in a folder
read_file(path) — fetch a specific file
run_test(test_name) — execute a test and show output
run_linter() — check code style
get_git_log(file_path, limit=5) — see recent changes
search_codebase(query) — grep-like search

When the agent needs to understand something, it asks. When it needs to validate a change, it runs tests. This keeps the initial context window reasonable and lets the agent focus on what actually matters for the task at hand.

Encode development conventions explicitly

Most codebases have unwritten rules. Your Python project might use type hints in some modules but not others. Your naming conventions might be inconsistent. Your error handling might be all try-except in some places and Result types elsewhere.

Document these as constraints, not suggestions:

# Development Conventions

## Code Style
- Use type hints everywhere (PEP 484)
- Max line length: 100 characters
- Use dataclasses for simple models, Pydantic for API schemas
- No star imports

## Error Handling
- Use custom exceptions defined in src/exceptions.py
- Log errors with structlog at the point of failure
- Don't swallow exceptions silently

## Testing
- Unit tests for business logic
- Integration tests for API endpoints
- Use fixtures for common setup
- Aim for >80% line coverage

When the agent generates code, it reads these rules before writing anything. This prevents it from mimicking bad patterns that exist elsewhere in your codebase.

Use Model Context Protocol (MCP) if you’re doing this at scale

If you’re setting up multiple agents or building this as infrastructure, MCP (Model Context Protocol) is the standard for connecting LLMs to tools and data sources. Claude Code, for example, supports MCP servers that expose your git repo, database, or custom tools as first-class integrations.

An MCP server for your codebase would expose:

Repository operations (read files, list directories, search)
Build and test commands
Linting and formatting
Deployment status and logs

Claude Opus 5 and Claude Fable 5.1 both support MCP natively. This beats manual setup because the agent gets a consistent interface to your environment without custom scripting.

Watch token costs when agents explore large codebases

An agent that reads random files from a 10MB codebase can waste thousands of tokens fetching irrelevant files. Set cost guards:

Limit search results to the top 5 files
Cache frequently-accessed files (architecture docs, core types)
Use Claude’s native prompt caching for static code reference material (check Claude’s current pricing model for cache read discounts)
Require the agent to justify why it’s reading a file before it fetches it

If you’re using Claude Opus 5 or Fable 5.1, prompt caching with a 90-minute TTL can make repeated agent runs much cheaper.

Real-world example: setting up a coding agent for a Django app

For a Django project, you’d create:

manifest.json — framework (Django), key apps, database engine, required environment variables
architecture.md — “We use Django ORM for queries. URLs in myapp/urls.py. Views are in myapp/views.py. Use Django signals for side effects.”
Git access — agent can fetch models.py, views.py, urls.py on demand, see recent changes
Tools — run_test(test_path), run_migrations(), check_migrations(), lint_code()
Conventions file — “Always run makemigrations before migrations. Never commit migrations by hand. Use Django form validation, not manual checks.”

This setup lets an agent make a Django model change, generate a migration, validate it with tests, and open a

Question via Hacker News