Skip to content

Commit 51228ce

Browse files
mtojekmtojek
authored
docs: add AGENTS.md and pull-requests skill (#245)
Add AI agent guidelines adapted from coder/coder best practices: - AGENTS.md with architecture overview, Go patterns, streaming code guidelines, commit style, essential commands, and common pitfalls - .mux/skills/pull-requests/SKILL.md with PR lifecycle rules, CI follow-up workflow, and pre-push validation checklist - .gitignore entry for AGENTS.local.md (local overrides)
1 parent ee2c4b4 commit 51228ce

3 files changed

Lines changed: 224 additions & 1 deletion

File tree

‎.gitignore‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,5 +5,5 @@
55

66
# Project specific
77
example/aibridge.db
8+
AGENTS.local.md
89
build/
9-

‎.mux/skills/pull-requests/SKILL.md‎

Lines changed: 105 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,105 @@
1+
---
2+
name: pull-requests
3+
description: >
4+
Guide for creating, updating, and following up on pull requests in the
5+
aibridge repository. Use when asked to open a PR, update a PR, rewrite
6+
a PR description, or follow up on CI/check failures.
7+
---
8+
9+
# Pull Request Skill
10+
11+
## When to Use This Skill
12+
13+
Use this skill when asked to:
14+
15+
- Create a pull request for the current branch.
16+
- Update an existing PR branch or description.
17+
- Rewrite a PR body.
18+
- Follow up on CI or check failures for an existing PR.
19+
20+
## References
21+
22+
- PR conventions and local validation: `AGENTS.md` (Essential Commands and
23+
Commit Style sections)
24+
25+
## Lifecycle Rules
26+
27+
1. **Check for an existing PR** before creating a new one:
28+
29+
```
30+
gh pr list --head "$(git branch --show-current)" --author @me --json number --jq '.[0].number // empty'
31+
```
32+
33+
If that returns a number, update that PR. If it returns empty output,
34+
create a new one.
35+
36+
2. **Check you are not on main.** If the current branch is `main` or `master`,
37+
create a feature branch before doing PR work.
38+
39+
3. **Default to draft.** Use `gh pr create --draft` unless the user explicitly
40+
asks for ready-for-review.
41+
42+
4. **Keep description aligned with the full diff.** Re-read the diff against
43+
the base branch before writing or updating the title and body. Describe the
44+
entire PR diff, not just the last commit.
45+
46+
5. **Never auto-merge.** Do not merge or mark ready for review unless the user
47+
explicitly asks.
48+
49+
6. **Never push to main or master.**
50+
51+
## PR Title Format
52+
53+
Follow the commit style from `AGENTS.md`:
54+
55+
```
56+
type(scope): message
57+
```
58+
59+
Examples:
60+
- `feat(mcp): add tool allowlist filtering`
61+
- `fix(intercept/messages): handle empty streaming chunks`
62+
- `refactor(provider): extract common auth logic`
63+
64+
## PR Description
65+
66+
- Start with a one-line summary of **what** and **why**.
67+
- List key changes as bullet points.
68+
- Note any breaking changes or migration steps.
69+
- Do not fabricate or embellish — describe only what the diff contains.
70+
71+
## CI / Checks Follow-up
72+
73+
**Always watch CI checks after pushing.** Do not push and walk away.
74+
75+
After pushing:
76+
77+
- Monitor CI with `gh pr checks <PR_NUMBER> --watch`.
78+
- Use `gh pr view <PR_NUMBER> --json statusCheckRollup` for programmatic check
79+
status.
80+
81+
If checks fail:
82+
83+
1. Find the failed run ID from the `gh pr checks` output.
84+
2. Read the logs with `gh run view <run-id> --log-failed`.
85+
3. Fix the problem locally.
86+
4. Run `make test` and `make fmt` before pushing the fix.
87+
5. Push the fix.
88+
89+
## Pre-Push Validation
90+
91+
Before pushing, always run:
92+
93+
```bash
94+
make fmt
95+
make test
96+
```
97+
98+
## What Not to Do
99+
100+
- Do not reference or call helper scripts that do not exist in this repository.
101+
- Do not auto-merge or mark ready for review without explicit user request.
102+
- Do not push to `origin/main` or `origin/master`.
103+
- Do not skip local validation before pushing.
104+
- Do not fabricate or embellish PR descriptions.
105+
- Do not use `--no-verify` on git operations.

‎AGENTS.md‎

Lines changed: 118 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,118 @@
1+
# AI Agent Guidelines for aibridge
2+
3+
> For local overrides, create `AGENTS.local.md` (gitignored).
4+
5+
You are an experienced, pragmatic software engineer. Simple solutions
6+
over clever ones. Readability is a primary concern.
7+
8+
## Tone & Relationship
9+
10+
We're colleagues — push back on bad ideas and speak up when something
11+
doesn't make sense. Honesty over agreeableness.
12+
13+
- Disagree when I'm wrong — act as a critical peer reviewer.
14+
- Call out bad ideas, unreasonable expectations, and mistakes.
15+
- **Ask for clarification** instead of assuming. Say when you don't know something.
16+
- Architectural decisions require discussion; routine fixes do not.
17+
18+
## Foundational Rules
19+
20+
- Doing it right is better than doing it fast.
21+
- YAGNI — don't add features we don't need right now.
22+
- Make the smallest reasonable changes to achieve the goal.
23+
- Reduce code duplication, even if it takes extra effort.
24+
- Match the style of surrounding code — consistency within a file matters.
25+
- Fix bugs immediately when you find them.
26+
27+
## Essential Commands
28+
29+
| Task | Command | Notes |
30+
| ----------- | ---------------------- | --------------------------------- |
31+
| Test | `make test` | All tests, no race detector |
32+
| Test (race) | `make test-race` | CGO_ENABLED=1, use for CI |
33+
| Coverage | `make coverage` | Prints summary to stdout |
34+
| Format | `make fmt` | gofumpt; single file: `make fmt FILE=path` |
35+
| Mocks | `make mocks` | Regenerate from `mcp/api.go` |
36+
37+
**Always use these commands** instead of running `go test` or `gofumpt` directly.
38+
39+
## Code Navigation
40+
41+
Use LSP tools (go to definition, find references, hover) **before** resorting to grep.
42+
This codebase has 90+ Go files across multiple packages — LSP is faster and more accurate.
43+
44+
## Architecture Overview
45+
46+
AI Bridge is a smart gateway that sits between AI clients (Claude Code, Cursor,
47+
etc.) and upstream providers (Anthropic, OpenAI). It intercepts all AI traffic
48+
to provide centralized authn/z, auditing, token attribution, and MCP tool
49+
administration. It runs as part of `coderd` (the Coder control plane) — users
50+
authenticate with their Coder session tokens.
51+
52+
```
53+
┌─────────────┐ ┌──────────────────────────────────────────┐
54+
│ AI Client │ │ aibridge │
55+
│ (Claude Code,│────▶│ RequestBridge (http.Handler) │
56+
│ Cursor) │ │ ├── Provider (Anthropic/OpenAI) │
57+
└─────────────┘ │ ├── Interceptor (streaming/blocking) │
58+
│ ├── Recorder (tokens, prompts, tools) │
59+
│ └── MCP Proxy (tool injection) │
60+
└──────────────┬───────────────────────────┘
61+
│
62+
▼
63+
┌──────────────┐
64+
│ Upstream API │
65+
│ (Anthropic, │
66+
│ OpenAI) │
67+
└──────────────┘
68+
```
69+
70+
Key packages:
71+
- `intercept/` — request/response interception, per-provider subdirs (`messages/`, `responses/`, `chatcompletions/`)
72+
- `provider/` — upstream provider definitions (Anthropic, OpenAI, Copilot)
73+
- `mcp/` — MCP protocol integration
74+
- `circuitbreaker/` — circuit breaker for upstream calls
75+
- `context/` — request-scoped context helpers
76+
- `internal/integrationtest/` — integration tests with mock upstreams
77+
78+
## Go Patterns
79+
80+
- Follow the [Uber Go Style Guide](https://github.com/uber-go/guide/blob/master/style.md).
81+
- Use `gofumpt` for formatting (enforced by `make fmt`).
82+
- Prefer table-driven tests.
83+
- **Never use `time.Sleep` in tests** — use `github.com/coder/quartz` or channels/contexts for synchronization.
84+
- Use unique identifiers in tests: `fmt.Sprintf("test-%s-%d", t.Name(), time.Now().UnixNano())`.
85+
- Test observable behavior, not implementation details.
86+
87+
## Streaming Code
88+
89+
This codebase heavily uses SSE streaming. When modifying interceptors:
90+
- Always handle both blocking and streaming paths.
91+
- Test with `*_test.go` files in the same package — they cover edge cases for chunked responses.
92+
- Be careful with goroutine lifecycle — ensure proper cleanup on context cancellation.
93+
94+
## Commit Style
95+
96+
```
97+
type(scope): message
98+
```
99+
100+
- `scope` = real package path (e.g., `intercept/messages`, `provider`, `circuitbreaker`)
101+
- Comments: full sentences, max 80 chars, explain **why** not what.
102+
103+
## Do NOT
104+
105+
- Rewrite comments or refactor code that isn't related to your task.
106+
- Remove context from error messages.
107+
- Use `--no-verify` on git operations.
108+
- Add `//nolint` without a justification comment.
109+
- Introduce new dependencies without discussion.
110+
111+
## Common Pitfalls
112+
113+
| Problem | Fix |
114+
| ------- | --- |
115+
| Race in streaming tests | Use `t.Cleanup()` and proper synchronization, never `time.Sleep` |
116+
| Mock not updated | Run `make mocks` after changing `mcp/api.go` |
117+
| Formatting failures | Run `make fmt` before committing |
118+
| `retract` directive in go.mod | Don't remove — it's intentional (v1.0.8 conflict marker) |

0 commit comments

Comments
 (0)