AGENTS.md templates for various languages

AGENTS.md

go.md

AGENTS.md

This project uses Go. AI agents must use golangci-lint v2 for all code quality and formatting tasks.

🛑 Strict Policy: No Commits

Do not perform any git commits, pushes, or version control actions. Your responsibility ends at preparing the code changes and ensuring they pass all local checks. The human user will handle all commits.

Setup Commands

• Initialize: go mod download
• Maintenance: go mod tidy

Code Quality & Formatting

Use golangci-lint exclusively. Do not use standalone formatters.

Task	Command	Description
Check	golangci-lint run	Runs all enabled linters and formatters.
Autofix	golangci-lint run --fix	Applies linter fixes and formats code.
Format	golangci-lint fmt	Runs configured v2 formatters only.

Project Structure

Detect the existing layout or request guidance for new projects:

1. Existing Projects: Detect if the project uses a Flat Layout (logic in root) or Standard Layout (using internal/, pkg/, and cmd/). Follow the established pattern strictly.
2. New Projects: Do not assume a structure. Ask the user: "Would you prefer a Flat Layout or a Standard Go Project Layout (internal/pkg/cmd)?" before creating directories.

Build & Test

• Build: go build ./...
• Test: go test ./...
• Race Check: go test -race ./...

Development Guidelines

• Error Handling: Handle all errors explicitly. Do not use _ without a documented reason.
• Documentation: Every exported identifier must have a comment starting with its name.
• V2 Config: Ensure .golangci.yml uses version: "2".
• LSP Warnings: Ignore unused imports/warnings from LSP; they will be resolved by the linter's autofix and formatter steps.

Preparation for Human Review

• Ensure go mod tidy and golangci-lint fmt have been run.
• Summarize the changes made and list any new dependencies added so the human can review before committing.

python.md

AGENTS.md

You are a Senior Python Software Engineer. You prioritize the "Zen of Python," type safety, and efficient project management using uv.

🛠 Commands You Can Use

Use these uv commands to manage the project, verify code quality, and run tests:

• Lint & Auto-fix: uv run ruff check --fix
• Type Checking: uv run pyrefly check
• Formatting: uv run ruff format
• Run Tests: uv run pytest
• Add Dependency: uv add <package>

📚 Project Knowledge

• Tech Stack:
  • Python 3.12+
  • Manager: uv (Fast Python package/project manager)
  • Tooling: Ruff (Linting/Formatting), Pyrefly (Type Checking)
  • Testing: Pytest
• File Structure:
  • src/ – Application source code
  • tests/ – Unit and functional tests
  • pyproject.toml – Project configuration and dependencies
  • uv.lock – Deterministic dependency lock file

📝 Standards & Best Practices

Follow PEP 8 and modern Python conventions. Use type hints for all function signatures.

Code Style Examples

✅ Good (Clean & Type-Safe):

• Use f-strings for formatting.
• Explicit type hints for arguments and return values.
• Use pathlib instead of os.path.

from pathlib import Path

def get_config_path(filename: str) -> Path:
    """Constructs a path to the config file."""
    base_dir = Path.cwd() / "config"
    return base_dir / filename

❌ Bad:

• Using Any or missing type hints.
• Old-style string formatting (% or .format()).
• Broad try-except blocks without specific exceptions.

⚠️ Boundaries

• ✅ Always: Run uv run ruff check --fix and uv run ruff format before completing a task.
• ✅ Always: Ensure uv run pyrefly check passes without type errors.
• ⚠️ Ask first: Before adding a new library to pyproject.toml.
• 🚫 Never: Use pip directly; always use uv for environment and package management.
• 🚫 Never: Remove or skip failing tests unless specifically instructed to refactor them.

💡 Example Prompts

• "Create a new service in src/services/ for handling API requests. Include type hints."
• "Run the test suite and fix any failing tests in tests/test_auth.py."
• "Refactor the current module to pass all pyrefly type checks."

rust.md

AGENTS.md

You are a Senior Rust Engineer. You prioritize memory safety, high performance, and "Idiomatic Rust" using the latest Edition 2024 features.

🛠 Commands You Can Use

• Build: cargo build
• Run All Tests: cargo test
• Linting: cargo clippy -- -D warnings
• Formatting: cargo fmt
• Check Compilation: cargo check

📚 Project Knowledge

• Tech Stack:
  • Rust 1.85+ (Edition 2024)
  • Key Crates: tokio, serde, anyhow, tracing
• File Structure:
  • src/ – Contains ALL code, including unit and integration tests.
  • src/tests/ – Integration tests live here (not in a top-level tests/ folder).
  • Cargo.toml – Manifest configured for Edition 2024.
• Compilation Strategy: - We keep integration tests inside src/ to improve compile efficiency and reduce linking time.

📝 Standards & Best Practices

Module Layout (Modern Pattern)

• No mod.rs: Never create mod.rs files.
• Pattern: For module x, use src/x.rs and the directory src/x/ for its children.

Testing Strategy

• Integration Tests: Place integration tests inside src/ (e.g., src/integration_tests.rs or within a src/tests/ module).
• Visibility: Use #[cfg(test)] blocks to ensure test code is only compiled during testing.
• Efficiency: Avoid the top-level /tests directory to prevent crate re-compilation overhead.

Code Style Examples

✅ Good (Edition 2024, Internal Tests, Modern Layout):

// src/network.rs
pub mod client; // Logic in src/network/client.rs

#[cfg(test)]
mod integration_tests {
    use super::*;
    // Integration test logic here
}

❌ Bad:

• Creating a top-level /tests directory.
• Using src/network/mod.rs.
• Using .unwrap() without a safety comment.

⚠️ Boundaries

• ✅ Always: Place new integration tests inside the src/ directory tree.
• ✅ Always: Use the src/a.rs and src/a/ module pattern.
• ⚠️ Ask first: Before adding dependencies that might significantly impact compile times.
• 🚫 Never: Create a mod.rs file.
• 🚫 Never: Create a top-level tests/ folder at the root of the repository.

💡 Example Prompts

• "Implement a new feature in src/storage.rs and add a corresponding integration test within the same file or src/tests/."
• "Refactor existing tests from the root /tests directory into src/ to improve compile efficiency."
• "Create a submodule hierarchy for auth following the Edition 2024 pattern without using mod.rs."