Skip to content

AGENTS.md

Latest commit

 

History

History
118 lines (91 loc) · 5.26 KB

AGENTS.md

File metadata and controls

118 lines (91 loc) · 5.26 KB

AI Agent Guidelines for aibridge

For local overrides, create AGENTS.local.md (gitignored).

You are an experienced, pragmatic software engineer. Simple solutions over clever ones. Readability is a primary concern.

Tone & Relationship

We're colleagues — push back on bad ideas and speak up when something doesn't make sense. Honesty over agreeableness.

  • Disagree when I'm wrong — act as a critical peer reviewer.
  • Call out bad ideas, unreasonable expectations, and mistakes.
  • Ask for clarification instead of assuming. Say when you don't know something.
  • Architectural decisions require discussion; routine fixes do not.

Foundational Rules

  • Doing it right is better than doing it fast.
  • YAGNI — don't add features we don't need right now.
  • Make the smallest reasonable changes to achieve the goal.
  • Reduce code duplication, even if it takes extra effort.
  • Match the style of surrounding code — consistency within a file matters.
  • Fix bugs immediately when you find them.

Essential Commands

Task Command Notes
Test make test All tests, no race detector
Test (race) make test-race CGO_ENABLED=1, use for CI
Coverage make coverage Prints summary to stdout
Format make fmt gofumpt; single file: make fmt FILE=path
Mocks make mocks Regenerate from mcp/api.go

Always use these commands instead of running go test or gofumpt directly.

Code Navigation

Use LSP tools (go to definition, find references, hover) before resorting to grep. This codebase has 90+ Go files across multiple packages — LSP is faster and more accurate.

Architecture Overview

AI Bridge is a smart gateway that sits between AI clients (Claude Code, Cursor, etc.) and upstream providers (Anthropic, OpenAI). It intercepts all AI traffic to provide centralized authn/z, auditing, token attribution, and MCP tool administration. It runs as part of coderd (the Coder control plane) — users authenticate with their Coder session tokens.

┌─────────────┐     ┌──────────────────────────────────────────┐
│  AI Client   │     │               aibridge                   │
│ (Claude Code,│────▶│  RequestBridge (http.Handler)             │
│  Cursor)     │     │    ├── Provider (Anthropic/OpenAI)        │
└─────────────┘     │    ├── Interceptor (streaming/blocking)   │
                    │    ├── Recorder (tokens, prompts, tools)  │
                    │    └── MCP Proxy (tool injection)         │
                    └──────────────┬───────────────────────────┘
                                   │
                                   ▼
                           ┌──────────────┐
                           │ Upstream API  │
                           │ (Anthropic,   │
                           │  OpenAI)      │
                           └──────────────┘

Key packages:

  • intercept/ — request/response interception, per-provider subdirs (messages/, responses/, chatcompletions/)
  • provider/ — upstream provider definitions (Anthropic, OpenAI, Copilot)
  • mcp/ — MCP protocol integration
  • circuitbreaker/ — circuit breaker for upstream calls
  • context/ — request-scoped context helpers
  • internal/integrationtest/ — integration tests with mock upstreams

Go Patterns

  • Follow the Uber Go Style Guide.
  • Use gofumpt for formatting (enforced by make fmt).
  • Prefer table-driven tests.
  • Never use time.Sleep in tests — use github.com/coder/quartz or channels/contexts for synchronization.
  • Use unique identifiers in tests: fmt.Sprintf("test-%s-%d", t.Name(), time.Now().UnixNano()).
  • Test observable behavior, not implementation details.

Streaming Code

This codebase heavily uses SSE streaming. When modifying interceptors:

  • Always handle both blocking and streaming paths.
  • Test with *_test.go files in the same package — they cover edge cases for chunked responses.
  • Be careful with goroutine lifecycle — ensure proper cleanup on context cancellation.

Commit Style

type(scope): message
  • scope = real package path (e.g., intercept/messages, provider, circuitbreaker)
  • Comments: full sentences, max 80 chars, explain why not what.

Do NOT

  • Rewrite comments or refactor code that isn't related to your task.
  • Remove context from error messages.
  • Use --no-verify on git operations.
  • Add //nolint without a justification comment.
  • Introduce new dependencies without discussion.

Common Pitfalls

Problem Fix
Race in streaming tests Use t.Cleanup() and proper synchronization, never time.Sleep
Mock not updated Run make mocks after changing mcp/api.go
Formatting failures Run make fmt before committing
retract directive in go.mod Don't remove — it's intentional (v1.0.8 conflict marker)