Querying the agent-platform repo with Claude Code

At a glance

• The agent-platform repo is the source of truth for how every agent actually works.
• You don’t need to be an engineer to read it. Use Claude Code as your interface.
• This page gives you setup + a starter prompt library + a guided tour. Budget: 30 minutes to first useful answer.

Why use Claude Code for this

The repo is large. Reading it folder-by-folder is the wrong way in unless you already know what you’re looking for. Claude Code lets you ask natural-language questions (“show me how Clara handles a timeout”) and follows symbol references across files for you.

What Claude Code is good at, for this repo:

• Summarising an agent’s flow end-to-end
• Finding all the places a pattern is used (e.g. “every place we register an MCP tool”)
• Drafting a new test that follows existing patterns
• Explaining a confusing block of code

What it’s bad at:

• Writing production code without review
• Anything that requires knowledge outside the repo (e.g. customer config that lives in a database)

Setup (5 min)

# 1. Clone the repo
git clone https://github.com/shipsy/agent-platform.git
cd agent-platform
 
# 2. Install Claude Code
# See https://docs.claude.com/en/docs/claude-code/setup
 
# 3. Open it
claude

The repo already ships with a .claude/CLAUDE.md that primes Claude with Shipsy-specific context (terminology, where agents live, where tools live). If it doesn’t, ping the platform team — that file should be there.

The codebase-navigator skill

Shipsy maintains a codebase-navigator skill that knows where every product area lives across all Shipsy repos. Always invoke it before asking Claude to grep the whole codebase:

> use the codebase-navigator skill to find where COD reconciliation lives

This saves you from Claude grepping 200K files looking for the wrong thing.

Starter prompt library

Copy/paste these. Each has a one-line note on what you should see if your session is set up right.

Understanding an agent

> Walk me through how Clara handles an inbound call from a customer
> whose order has 2 failed delivery attempts. Show me the actual files
> and functions involved at each step.

Expected: a sequence of file paths + functions tracing from the inbound webhook → supervisor → Clara → tool calls → response.

> Compare how Maya and Atlas differ in their orchestration logic.
> What's a use case where you'd reach for one over the other?

Expected: a side-by-side analysis with file references. If Claude can’t find Atlas, the agent may not be in this repo yet — check with the platform team.

Understanding the platform

> Show me every place we register a new MCP tool, and the pattern
> for adding one. Then walk me through adding a hypothetical tool
> called "get_courier_rating".

Expected: references to the MCP registration file(s) + a step-by-step on how to add a new tool.

> Which models can the platform call, and where is the
> model-selection logic? When would the same agent end up calling
> two different models?

Expected: a list of supported model providers + the routing/fallback logic.

> Find the eval-set format and show me an example eval for any
> agent. Then draft 3 new evals for the same agent covering edge
> cases that aren't currently tested.

Expected: the eval schema + an existing example + 3 new drafts. Don’t commit Claude’s drafts without review.

Debugging

> What happens when an agent's tool call times out? Show me the
> retry path, what gets logged, and where the failure surfaces in
> observability.

Expected: timeout handler code + retry logic + log/metric emission.

> A customer says Vera is making outbound calls at 3am their time.
> Where in the code is the time-of-day check, and how is the
> customer's timezone resolved?

Expected: a pointer to scheduling logic + timezone handling. May reveal a gap if no such check exists.

Onboarding to the repo

> I'm new to this repo. Give me a 10-minute tour: where do
> agents live, where do tools live, where does the orchestrator
> live, and what's the single most important file I should read
> first?

Expected: a structured walkthrough + one recommended starter file.

A guided tour (30 min)

Run these in order. Each one builds on the previous.

1. Lay of the land — Give me a directory-level overview. What's in each top-level folder?
2. The orchestrator — Show me the supervisor agent's entry point. Walk me through one end-to-end execution.
3. A simple agent — Pick the simplest agent in this repo. Explain it line by line.
4. A tool — Show me one MCP tool definition. Explain the contract — what does the agent see, what does the tool do?
5. Memory — Where do we read from / write to long-term memory? Show me one place we do RAG.
6. Evals — Show me how I'd run the eval suite for one agent locally.
7. Observability — Where do we emit metrics and logs? How would I trace a single conversation end-to-end?

If any step takes more than ~5 minutes or returns “I can’t find this”, that’s a documentation gap. File it in the repo’s issues with [hub-feedback] in the title.

Anti-patterns

• Don’t paste customer data into prompts. Even in a local Claude session. Use anonymised samples.
• Don’t run bash from a Claude session against a connected production DB. Local sandbox or read-only replica only.
• Don’t ask Claude to write production code without engineering review. Use it to draft, then a human reviews the diff.
• Don’t treat Claude’s summaries as the source of truth. It can hallucinate file structures, function names, and behaviour. Always verify against the actual file before relying on the answer for a customer.
• Don’t ask vague questions (“how does Shipsy work?”). Be specific — agent name, file path, behaviour. The narrower the question, the better the answer.

When to escalate to engineering

Sources

• agent-platform repo
• Claude Code docs
• Shipsy codebase-navigator skill

Changelog

• 26 May 2026: Initial draft.