Skip to content

Latest commit

 

History

History
123 lines (82 loc) · 3.97 KB

AGENTS.md

File metadata and controls

123 lines (82 loc) · 3.97 KB

Repository Guidelines

This is a repository full of code written in Go. Use the table driven testing skill when possible.

Development Workflow

Build, Test & Development Commands

Command Description
npm test Runs tests with go test ./....
go build ./... Compiles all Go packages.
go test ./... Runs all tests.
npm run format Formats Go (goimports) and JS/HTML (prettier).

Code Formatting & Style

  • Go – use go fmt/go tool goimports; tabs for indentation, camelCase for variables, PascalCase for exported identifiers
  • JavaScript/JSON/YAML – formatted with Prettier (2-space tabs, trailing commas, double quotes)
  • Files are snake_case; packages use lower-case module names
  • Run npm run format before committing

Testing

  • Tests are written in Go using the standard testing package (*_test.go)
  • Keep test files next to the code they cover
  • Run the full suite with npm test or go test ./...
  • Package examples are in example_test.go for Godoc

Example Code Error Handling

When writing example code in *_example_test.go files, follow this pattern for error handling:

result, err := client.SomeOperation(ctx)
if err != nil {
    log.Fatal(err) // handle the error here
}

The // handle the error here comment indicates to users that they should replace log.Fatal(err) with appropriate error handling for their use case (logging, retry, cleanup, etc.).

Test Imports

When writing test code that may use environment variables for configuration, import the godotenv autoload package:

import (
    _ "github.com/joho/godotenv/autoload"
    // ... other imports
)

This automatically loads environment variables from a .env file in the project root, which is useful for integration tests that require credentials or other configuration.

Code Quality & Security

Commit Guidelines

Commit messages follow Conventional Commits format:

[optional scope]: <description>
[optional body]
[optional footer(s)]

Types: feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert

  • Add ! after type/scope for breaking changes or include BREAKING CHANGE: in the footer.
  • Keep descriptions concise, imperative, lowercase, and without a trailing period.
  • Reference issues/PRs in the footer when applicable.
  • ALL git commits MUST be made with --signoff. This is enforced by DCO checks.

Attribution Requirements

AI agents must disclose what tool and model they are using in the "Assisted-by" commit footer:

Assisted-by: [Model Name] via [Tool Name]

Example:

Assisted-by: GLM 4.7 via Claude Code

Helpful Documentation

When asked about various services or tools, use these resources to help you:

Pull Request Requirements

  • ALL pull requests MUST use the template in .github/pull_request_template.md
  • Include a clear description of changes
  • Reference any related issues
  • Pass CI (npm test)
  • PR titles must follow Conventional Commits format (enforced by linting)

Security Best Practices

  • Secrets never belong in the repo; use environment variables
  • Run npm audit periodically for JS tooling vulnerabilities

AI Assistant Instructions

Task Execution

When undertaking a task, pause and ask the user for intent before writing code.

Technical Guidelines

  • Go – follow the standard library style; prefer table-driven tests
  • JSON/YAML – double quotes, two-space indentation
  • Run npm run format to apply Prettier and goimports formatting

This file is consulted by the repository's tooling. Keep it up-to-date as the project evolves.