Skip to main content

Quick Start: Go

Open Repo Download ZIP

git clone https://github.com/AEEF-AI/aeef-quickstart.git my-project

This guide walks through setting up the AEEF Quick Start tier for a Go project. By the end, you will have a running Chi-based HTTP service with AI tool configuration, linting, testing, security scanning, and CI -- all enforcing AEEF standards.

Prerequisites​

  • Go 1.22+ -- Required for enhanced standard library routing and toolchain improvements
  • Git 2.30+ -- For branch protection and conventional commits
  • An AI coding tool configured for your IDE

Verify your environment:

go version    # go1.22.x
git --version # 2.30+

Step-by-Step Setup​

1. Create the Project​

git clone https://github.com/AEEF-AI/aeef-quickstart.git my-go-project
cd my-go-project

# Run the Go setup
./scripts/setup.sh --lang go

2. Download Dependencies​

go mod download

3. Install Dev Tools​

# golangci-lint
go install github.com/golangci-lint/golangci-lint/cmd/golangci-lint@latest

# govulncheck for vulnerability scanning
go install golang.org/x/vuln/cmd/govulncheck@latest

4. Verify the Configuration​

make check

This executes: golangci-lint run, go vet, go test -race -coverprofile, and semgrep.

File-by-File Walkthrough​

.golangci.yml -- Linter Configuration​

golangci-lint aggregates dozens of Go linters into a single tool. The configuration enforces code quality aligned with PRD-STD-006:

linters:
  enable:
    - errcheck
    - gosimple
    - govet
    - ineffassign
    - staticcheck
    - unused
    - gocritic
    - gocyclo
    - gosec
    - revive
    - misspell

linters-settings:
  gocyclo:
    min-complexity: 10
  gocritic:
    enabled-tags:
      - diagnostic
      - style
      - performance
  gosec:
    severity: medium
    confidence: medium

issues:
  max-issues-per-linter: 0
  max-same-issues: 0

Makefile -- Build and Quality Commands​

The Makefile provides consistent commands for all quality checks:

.PHONY: lint test security check

lint:
	golangci-lint run ./...

test:
	go test -race -coverprofile=coverage.out -covermode=atomic ./...
	@go tool cover -func=coverage.out | grep total | awk '{print $$3}' | \
		awk -F. '{if ($$1 < 80) {print "Coverage below 80%"; exit 1}}'

security:
	govulncheck ./...
	semgrep --config .semgrep/ .

check: lint test security

go.mod -- Dependency Management​

Dependencies are managed with Go modules and pinned to specific versions, enforcing PRD-STD-008:

module github.com/your-org/my-go-project

go 1.22

require (
    github.com/go-chi/chi/v5 v5.1.0
    github.com/go-playground/validator/v10 v10.22.0
)

.cursorrules -- Cursor IDE Configuration​

You are assisting on a Go project governed by AEEF Standards.
All AI-generated code MUST:
- Follow idiomatic Go patterns (error handling, naming conventions)
- Include table-driven tests for any new functions
- Handle all errors explicitly (no _ = err)
- Use structured logging (slog)
- Never introduce dependencies without explicit approval

.github/workflows/ci.yml -- CI Pipeline​

name: CI
on:
  pull_request:
  push:
    branches: [main]

jobs:
  quality:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-go@v5
        with:
          go-version: "1.22"
      - run: go mod download
      - run: golangci-lint run ./...
      - run: go vet ./...
      - run: go test -race -coverprofile=coverage.out ./...
      - run: govulncheck ./...
      - run: semgrep --config .semgrep/ .

.semgrep/ -- Security Rules​

Custom Semgrep rules for Go:

  • ai-code-patterns.yml -- Detects AI-generated anti-patterns (hardcoded secrets, disabled TLS verification, panic in library code)
  • go-security.yml -- Go-specific rules (SQL injection via string concatenation, insecure random, unvalidated redirects)

Running the Example Application​

# Development with hot reload (using air)
air

# Build and run directly
go build -o bin/server ./cmd/server
./bin/server

# Run with race detector during development
go run -race ./cmd/server

The example application is a Chi-based HTTP service with health check, user endpoints, and middleware demonstrating AEEF-compliant patterns for error handling, input validation, and structured logging.

Making Your First AI-Assisted PR​

  1. Create a feature branch:

    git checkout -b feat/add-user-handler

  2. Use your AI tool to generate a new handler or service function.

  3. Write table-driven tests and verify coverage:

    go test -race -coverprofile=coverage.out ./...
    go tool cover -html=coverage.out -o coverage.html

  4. Run the full suite:

    make check

  5. Commit and push:

    git add .
    git commit -m "feat: add user creation handler with validation"
    git push -u origin feat/add-user-handler

  6. Open a PR and complete the AI-disclosure checklist.

Running Security Scans Locally​

# Go vulnerability database check
govulncheck ./...

# Semgrep SAST scan
semgrep --config .semgrep/ .

# gosec security scanner (included via golangci-lint)
golangci-lint run --enable gosec ./...

Next Steps​

Last updated on by BalrogEg