AGENTS.md files provide a standardized way to configure AI agent behavior across different AI coding tools.

AGENTS.md

Autonomous AI Agent Configuration & SDLC Protocol

1. Primary Directives & Self-Management

This document defines the behavioral and execution framework for autonomous AI coding agents. It ensures robust self-management, continuous execution, and context awareness regardless of the specific AI provider, LLM, or programming language in use.

Execution Protocol:

1. Environment Discovery: Upon initialization, automatically search for and ingest local rules (e.g., .cursorrules, .agentrules), workspace constraints, and available MCP (Model Context Protocol) / LSP servers.
2. Autonomous Navigation: Decompose tasks and use generic capabilities (File I/O, Codebase Search, CLI Execution) to independently navigate blockers.
3. Self-Correction: Exhaust all alternative paths (e.g., fixing failed tests, installing missing dependencies, reading framework docs, web search for latest knowledge) before halting for human intervention.
4. Context Condensing: Continuously summarize file reads, terminal outputs, and previous logic to operate strictly within token context limits while preserving state.
5. Provider Agnosticism: Rely on standard CLI streams (stdin/stdout), agnostic system commands, and broad rule-sets rather than vendor-specific plugins.

---

2. SDLC (Software Development Life Cycle) Workflow

Agents must operate within a rigid, sequential SDLC pipeline. Transition between phases requires emitting a Checkpoint Signal to ensure traceable continuity.

Signal Format: [CP:{PHASE}] {STATUS} - {SUMMARY}

Checkpoint	SDLC Phase	Agent Action	Quality Gate / Exit Criteria
CP:REQ	Requirements & Analysis	Parse specs, index the codebase, load custom rules, and define acceptance criteria.	Ambiguities resolved; clear success metrics defined.
CP:PLAN	Architecture & Design	Formulate technical design, define API/module contracts, and plan subagent/mode delegation.	Architecture documented; test strategies finalized.
CP:BUILD	Implementation	Execute Test-First Development (TDD). Build independent libraries using language-agnostic standards.	Code generated; core logic fulfills specifications.
CP:TEST	Testing & Verification	Run linters, unit/integration tests, and static analysis via CLI/LSP. Verify security boundaries.	All tests pass (Green); zero P0/P1 defects.
CP:DEPL	Review & Deployment	Condense context, document decisions/trade-offs, and package artifacts.	Output perfectly matches specs; final summary emitted.

---

3. Subagent Delegation & Role Orchestration

Complex workflows require dividing work across custom modes (e.g., Architect, Coder, Reviewer) or parallel subagents.

Delegation Protocol:

1. Identify Modality: Classify the task type (e.g., Database Migration, Frontend, CI/CD Script) to select the appropriate mode, rule-set, or subagent.
2. Context Packaging: Pass strictly isolated context to the sub-process:
   • Intent & Constraints: Clear objective, resource limits, and language-specific instructions.
   • Input Artifacts: Targeted file paths or semantic search results (minimize token bloat).
   • Verification: Explicit, programmatic success criteria.
3. Aggregate & Condense: Upon completion, the primary agent must validate the subagent's output, condense the findings, and integrate them into the master SDLC sequence.

---

4. Core Engineering Philosophy

Specification-Driven Development (SDD)

• Specs as Truth: Code is merely an expression of the specifications. Generate unambiguous, executable specifications before writing application logic.
• Bidirectional Feedback: Use test results and system errors to continuously refine the initial spec and custom instructions.

Test-First (Non-Negotiable)

• Write failing tests (Red) → Implement core logic → Verify passing tests (Green) → Refactor for standards.
• Never assert a feature is complete until verified by an automated test or explicit command execution.

Library-First & Decoupled Architecture

• Every feature starts as a standalone, modular library with minimal dependencies.
• Enforce strict separation of concerns using explicit data contracts (e.g., JSON, strict types, CLI args).

---

5. Universal Quality Framework

Priority Definitions

Priority	Category	Blocking	Required Action
P0	Security vulnerabilities (hardcoded secrets, injections), data loss	YES	Halt execution; fix immediately.
P1	Core logic errors, failing tests, severe performance degradation	YES	Fix before advancing the SDLC phase.
P2	Code smells, missing non-critical docs, minor technical debt	NO	Document in codebase/tracker; proceed.
P3	Style/formatting inconsistencies	NO	Auto-format via CLI; do not iterate.

Agnostic Quality Gates

• Security: Zero hardcoded credentials. Validate all inputs at I/O boundaries.
• Code Quality: Adhere to detected language conventions (e.g., PEP8, GoFmt, Prettier). Enforce low cyclomatic complexity (< 10).
• Architecture: Zero circular dependencies. Prefer composition over inheritance.
• Error Handling: Never swallow errors silently. Fail fast, validate types, and generate investigation-ready logs.

---

6. Code & Context Standards

Dynamic Context Management

• Use codebase indexing to locate definitions rather than blindly reading whole directories.
• Strip generated artifacts and external node_modules/vendor folders from context reading.

Idiomatic Implementation

• Follow the idiomatic style of the target ecosystem automatically.
• Document the why (architectural decisions, trade-offs) in comments, not the what (which should be self-evident from code).
• Keep functions concise (< 50 lines) with a maximum of 3 nesting levels.

Performance

• Profile bottlenecks using language-specific tooling before optimizing.
• Ensure strict lifecycle management: explicitly close network requests, file handles, and database connections.

Go-Engineer.md

Go-Engineer Skill

Name: Go-Engineer Description: Expert Go development guidance covering code quality, performance optimization, naming conventions, and best practices. Use when writing, reviewing, or refactoring Go code. Version: 1.0 Author: Kawin Viriyaprasopsook Tags: go, golang, performance, best-practices, code-quality

---

Core Principles

The 10x Commandments

1. Write packages, not programs — main parses flags/handles errors; domain packages do real work. Return data, not prints. Return errors, don't panic.
2. Test everything — Test names are sentences. Focus on user-visible behavior. Add integration tests. Use testscript for binaries.
3. Write code for reading — Use consistent naming: err, data, buf, ctx, req, resp, i. Extract methods to simplify.
4. Be safe by default — Make zero values useful. Use validating constructors. Use WithX methods for config. Use named constants, not magic values.
5. Wrap errors, don't flatten — Use sentinel errors with errors.Is(). Wrap with fmt.Errorf("%w"). Never compare errors with ==.
6. Avoid mutable global state — Use sync.Mutex or guard goroutines. Don't use http.DefaultServeMux or DefaultClient.
7. Use structured concurrency sparingly — Confine goroutines. Use WaitGroup or errgroup. Take channel aspects (chan<- or <-chan), not both.
8. Decouple code from environment — Only main accesses os.Getenv/os.Args. Use go:embed for static data. Use xdg for paths.
9. Design for errors — Always check errors. Handle/retry where possible. Reserve panic for internal errors only.
10. Log only actionable information — Use slog for JSON output. Don't log secrets. Use tracing for request-scoped debugging.

---

Naming Conventions

Identifiers

• Unexported: camelCase
• Exported: PascalCase
• Acronyms: Consistent case (apiKey or APIKey, not ApiKey). ID always caps (userID, OrderID)
• No type names: count not intCount; results not resultSlice
• Avoid clashes: Don't use builtin names (int, bool, min, len) or stdlib packages (json, url, log)
• ASCII only: pi not π; naiveBayes not naïveBayes

Packages

• Lowercase, no separators: ordermanager not orderManager or order_manager
• Short, descriptive nouns: orders, customer, slug
• Avoid catch-alls: utils, helpers, common, types
• Avoid stdlib conflicts: links not url; mailer not mail

Files

• Lowercase, one word if possible: server.go, cookie.go
• Multi-word: pick one style consistently (routingindex.go or routing_index.go)
• Special suffixes: _test.go, _linux.go, _amd64.go

Methods & Receivers

• Receiver: 1-3 chars, consistent per type (c, o, hs). Never this, self, me
• Getters: No Get prefix (Address() not GetAddress())
• Setters: Use Set prefix (SetAddress())
• Avoid chatter: customer.New() not customer.NewCustomer()

Interfaces

• Single-method: method name + -er (Reader, Writer, Authorizer)
• Don't include Interface in name

Identifier Length

• Short scope (loops, small functions): Short names OK (i, p, c)
• Long scope (package-level, widely used): Descriptive names required

---

Performance Patterns

Memory Management

• Object pooling: Reuse objects to reduce GC pressure
• Preallocate: make([]T, 0, capacity) for slices/maps
• Struct alignment: Order fields by size to minimize padding
• Avoid interface boxing: Minimize interface conversions
• Zero-copy: Use slicing/buffer tricks to avoid data copying
• Escape analysis: Help values stay on stack (avoid pointers when unnecessary)

Concurrency

• Worker pools: Fixed-size goroutine pools to limit resources
• Atomic operations: Use sync/atomic for simple shared state
• Lazy init: sync.Once for expensive setup
• Immutable sharing: Share data without locks by making it immutable
• Context propagation: Use context for timeouts/cancellation

I/O Optimization

• Buffering: Use bufio.Reader/Writer to minimize syscalls
• Batching: Combine small operations to reduce round trips

Compiler Tuning

• Build flags: -gcflags and -ldflags for optimization
• Profile first: Use pprof before optimizing

---

Code Review Checklist

• Package structure: domain logic separate from main
• Error handling: wrapped with context, checked everywhere
• Naming: follows conventions, no clashes, appropriate length
• Concurrency: goroutines confined, proper cleanup with context/WaitGroup
• Globals: no mutable package-level variables
• Tests: exist for public APIs, meaningful names
• Logging: only actionable errors, no secrets
• Performance: preallocated slices, minimal allocations in hot paths
• Export: minimal surface area, unexported by default