Skip to content

AGENTS.md

Latest commit

 

History

History
104 lines (83 loc) · 3.56 KB

AGENTS.md

File metadata and controls

104 lines (83 loc) · 3.56 KB

codex-gateway Agent Guide

Purpose

This file defines repository-specific operating rules for coding agents working in codex-gateway. Prefer existing project patterns over invention.

Project Snapshot

  • Language: Go (1.26+)
  • CLI framework: cobra
  • HTTP stack: net/http
  • Config format: YAML (gopkg.in/yaml.v3)
  • Testing: go test + httptest

Sources Of Truth

Environment Setup

go mod download

Build, Lint, Test Commands

Core Verification

go test ./...
go test -race ./...
go build ./cmd/codex-gateway

Focused Test Workflows

go test ./internal/server -run TestProxy -v
go test ./internal/oauth -run TestClient_AuthenticateSuccess -v
go test ./internal/auth -run TestManager -v

Architecture Boundaries

Maintain one-way dependency flow:

config/oauth/auth -> upstream -> server -> cli

Rules:

  • Keep transport logic in internal/server and internal/upstream.
  • Keep token lifecycle logic in internal/auth and OAuth protocol logic in internal/oauth.
  • Keep internal/cli thin (wiring and process orchestration only).
  • Avoid hidden globals; pass dependencies explicitly.

Code Style Guidelines

Imports and Packages

  • Use module-rooted imports (codex-gateway/internal/...).
  • Keep package responsibilities focused.
  • Avoid import-time side effects.

Formatting

  • Use gofmt for all Go source files.
  • Add comments only when logic is non-obvious.
  • Keep production code and comments in English.

Types and Error Handling

  • Prefer explicit struct contracts at package boundaries.
  • Return actionable errors with context (fmt.Errorf("...: %w", err)).
  • Never silently swallow errors.

Testing Expectations

  • Prefer TDD for feature and bugfix work.
  • Keep tests near package behavior (*_test.go in same package directory).
  • Cover happy paths and edge/failure paths.
  • Run targeted tests first, then full suite for substantial changes.

Documentation Expectations

  • If behavior changes, update README.md, README.zh-CN.md, and relevant docs under docs/.
  • Keep architecture and privacy claims aligned with implementation.
  • Do not document features as complete before tests pass.

Git Workflow Expectations

  • Branches: main, dev, and feat/* or feature/*.
  • Commit style: Angular conventional commits (feat:, fix:, docs:, chore:).
  • Merge feature branches into dev first; merge dev to main for release.

Agent Checklist Before Finishing

  1. Changes follow architecture and style constraints.
  2. Relevant targeted tests were run.
  3. Full test suite was run for substantial changes.
  4. User-facing docs were updated for behavior changes.
  5. No conflict with .opencode/skills/ rules.