Step-by-step: Setting up Claude Code for a multi-language microservices repo.

Hey folks! 👋 I've been experimenting with Claude Code on our main microservices repository at work, and I finally got a workflow that feels smooth. Our stack is a bit of a zoo—Go services, Python data pipelines, some legacy Node.js, and a sprinkle of TypeScript frontends—so getting an AI assistant to play nice with all of it was tricky.

Here’s my step-by-step setup, focusing on the config and context management that made it work.

**First, the key was creating a `.clauderc` file at the repo root.** This tells Claude about our project structure and important patterns.

```json
{
"context": {
"directories": [
"api/",
"pkg/",
"internal/",
"scripts/",
"deploy/"
],
"extensions": [".go", ".py", ".ts", ".js", ".yaml", ".yml", ".json"],
"ignore": ["node_modules/", "vendor/", "*.log", "coverage/"]
},
"instructions": "Primary languages: Go, Python, TypeScript. Our Go services use Echo framework. Python uses FastAPI. Always suggest unit tests. Reference our logging format: structured JSON. Alert thresholds are in deploy/alerts.yaml."
}
```

**Then, I made a few custom prompts as markdown files in a `.claude/prompts/` folder:**
- `review_microservice.md` – for code review focusing on inter-service communication
- `add_observability.md` – patterns for adding metrics, logs, and traces
- `debug_slow_endpoint.md` – a checklist for performance issues

**The real win was using Claude Code's @-mentions with specific service directories.** Instead of opening the whole repo, I'll start a chat and say:

> "@api/userservice – Can you review this new GET /users endpoint for pagination? Look for race conditions."

This keeps the context focused and prevents it from getting lost in our 50+ service repo.

**A couple of pitfalls I hit early on:**
* Without the `.clauderc`, it kept trying to read `node_modules` and vendor files, timing out.
* It sometimes suggested generic solutions that didn't fit our internal SDKs. Adding those SDK paths to the `directories` array helped a ton.
* For truly cross-service changes, I now start a separate chat per service and then a final one to discuss integration points.

The result? I'm using it mostly for:
* Generating boilerplate for new endpoints (it knows our patterns now)
* Explaining complex logic in older pipelines
* Writing integration test scenarios
* Drafting incident post-mortem outlines from log snippets

It's not replacing our human reviews, but it's a fantastic first pass, especially for catching common gotchas in languages you're less familiar with. Anyone else setting this up for a polyglot repo? I'm curious how you're handling cross-language dependencies.