Skip to content

AGENTS.md

Latest commit

 

History

History
262 lines (198 loc) · 8.79 KB

AGENTS.md

File metadata and controls

262 lines (198 loc) · 8.79 KB

AGENTS.md

This file provides quick, actionable guidance for AI coding agents working on the oastools project. For comprehensive details, see CLAUDE.md.

⚠️ BRANCH PROTECTION: The main branch has push protections. Before making ANY changes, verify you're on a feature branch (git branch --show-current). If on main, create a branch first: git checkout -b <type>/<description>

Project Overview

oastools is a Go-based CLI tool for working with OpenAPI Specification (OAS) files. It supports parsing, validating, fixing, joining, converting, and comparing OAS documents across versions 2.0, 3.0.x, 3.1.x, and 3.2.0.

Module: github.com/erraggy/oastools
Go Version: 1.25+

Dev Environment Setup

CRITICAL: Install golangci-lint v2 before making code changes:

curl -sSfL https://raw.githubusercontent.com/golangci/golangci-lint/master/install.sh | sh -s -- -b $(go env GOPATH)/bin v2.1.0
export PATH=$PATH:$(go env GOPATH)/bin
golangci-lint version  # Should show v2.1.0

Quick Commands

# Build and test workflow (run after every code change)
make check          # Runs tidy, fmt, lint, test, and git status

# Individual commands
make build          # Build binary to bin/oastools
make test           # Run all tests with race detection
make test-coverage  # Generate and view HTML coverage report
make fmt            # Format all Go code
make lint           # Run golangci-lint (requires v2 installation)

# Benchmarks
make bench          # Run benchmarks
make bench-save     # Save new benchmark baseline (only if changes affect performance)

Testing Requirements

ALL exported functionality MUST have comprehensive tests:

  • Positive cases (valid inputs work)
  • Negative cases (errors handled correctly)
  • Edge cases (nil, empty, boundary conditions)
  • Integration cases (components work together)

Benchmark tests MUST use Go 1.24+ pattern:

func BenchmarkOperation(b *testing.B) {
    // Setup
    source, _ := parser.ParseWithOptions(...)
    
    for b.Loop() {  // ✅ Use b.Loop(), NOT for i := 0; i < b.N; i++
        _, err := Operation(source)
        if err != nil {
            b.Fatal(err)
        }
    }
}

Code Style & Patterns

Use package constants instead of string literals:

  • HTTP Methods: httputil.MethodGet, httputil.MethodPost, etc.
  • HTTP Status Codes: httputil.ValidateStatusCode(), httputil.StandardHTTPStatusCodes
  • Severity Levels: severity.SeverityError, severity.SeverityWarning, etc.

Format preservation:

  • Parser, converter, and joiner preserve input file format (JSON or YAML)
  • Format detected from file extension or content
  • First file determines output format for joiner

Type handling in OAS 3.1+:

// schema.Type can be string or []string - always use type assertions
if typeStr, ok := schema.Type.(string); ok {
    // Handle string type
} else if typeArr, ok := schema.Type.([]string); ok {
    // Handle array type
}

Pointer semantics:

// Use pointer slices for nested structures
servers := []*parser.Server{
    &parser.Server{URL: "https://api.example.com"},  // ✅ Correct
}

Security Fixes

Size computation overflow (CWE-190):

capacity := 0
sum := uint64(len(a)) + uint64(len(b))
if sum <= uint64(math.MaxInt) {
    capacity = int(sum)
}
result := make([]string, 0, capacity)

Always check for vulnerabilities:

govulncheck ./...

Boundaries - DO NOT Modify

  • .github/workflows/ - CI/CD workflows (unless specifically requested)
  • testdata/ - Test fixtures (unless adding new test cases)
  • vendor/, bin/, dist/ - Generated artifacts
  • go.mod, go.sum - Only modify when explicitly adding/removing dependencies
  • .goreleaser.yaml - Release configuration
  • benchmarks/ - Benchmark data (see BENCHMARK_UPDATE_PROCESS.md)

Acceptance Criteria

A task is complete when:

  1. ✅ All required functionality is implemented
  2. ✅ New/modified exported functions have comprehensive tests
  3. ✅ make build succeeds without errors
  4. ✅ make test passes with no failures
  5. ✅ Code is formatted and follows existing patterns
  6. ✅ Public APIs have godoc comments
  7. ✅ No regressions in existing tests
  8. ✅ No new security vulnerabilities (govulncheck)

For documentation-only changes, only items 3, 6, and 7 apply.

Commit & PR Format

Commit messages:

  • First line: Conventional commit format (max 72 chars)
  • Examples: feat: add webhook support to parser, fix: handle nil pointer in converter

PR format:

  • Title: Same as commit message
  • Body: Detailed markdown explaining reasoning, changes, and context

Common Pitfalls

  1. Type assertions: Don't assume schema.Type is always a string - check both string and []string
  2. Pointer slices: Use &Type{...} for pointer semantics, not value types
  3. Conversion issues: Track all lossy conversions or unsupported features
  4. Deep copy: Never mutate source documents - use generated DeepCopy() methods (e.g., doc.DeepCopy()), never JSON marshal/unmarshal
  5. Operation-level overrides: Check operation-level fields before falling back to document-level
  6. Version features: Explicitly handle version-specific features during conversion

Architecture

cmd/oastools/     - CLI entry point
parser/           - Parse YAML/JSON OAS files, resolve refs
validator/        - Validate OAS against spec schema
fixer/            - Automatically fix common validation errors
converter/        - Convert between OAS versions
joiner/           - Join multiple OAS files
overlay/          - Apply OpenAPI Overlay transformations
differ/           - Compare and diff OAS files
generator/        - Generate Go code from OAS files
builder/          - Build OAS documents programmatically
httpvalidator/    - Runtime HTTP request/response validation
walker/           - Traverse OAS documents with typed handlers
oaserrors/        - Structured error types for programmatic handling
internal/         - Shared utilities (httputil, severity, issues, mcpserver)
testdata/         - Test fixtures

Each public package includes doc.go (package docs) and example_test.go (godoc examples).

Development Agents

Four specialized agents streamline the development workflow. They are automatically invoked based on context and can chain together.

Agent Overview

Agent Purpose Auto-triggers when
Architect Design implementation plans Starting features, planning refactors, architectural decisions
Maintainer Code review & standards After code changes, before commits, after Developer completes
Developer Execute plans (checkpoint mode) After Architect plans, implementation requests, bug fixes
DevOps Engineer Process & tooling Releases, CI/CD, benchmarks, dependencies

Workflow Chain

User Request
     │
     ▼
┌─────────────┐
│  Architect  │  ← Plans the implementation
└──────┬──────┘
       │
       ▼
┌─────────────┐
│  Developer  │  ← Implements in phases with checkpoints
│ (pause)     │ ──── User: "continue" ────┐
└──────┬──────┘                           │
       │ ◄────────────────────────────────┘
       ▼
┌─────────────┐
│ Maintainer  │  ← Reviews changes
└──────┬──────┘
       │
       ▼
┌─────────────┐
│   DevOps    │  ← Prepares release (when needed)
└─────────────┘

Checkpoint Mode (Developer)

The Developer agent pauses between implementation phases:

  1. Implements one phase
  2. Runs tests
  3. Shows changes summary
  4. Pauses for approval
  5. On "continue" → next phase
  6. After final phase → invokes Maintainer

Review Severity Levels (Maintainer)

Level Icon Meaning
Critical 🔴 Must fix before merge (bugs, security, breaking changes)
Warning 🟡 Should fix (standards violations, missing tests)
Suggestion 🔵 Consider (style, optional improvements)

Agent Files

Located in .claude/agents/:

  • architect.md - Planning and design
  • maintainer.md - Code review and standards
  • developer.md - Implementation execution
  • devops-engineer.md - DevOps and tooling

Resources