Skip to content
BranchesTags

Repository files navigation

Agent Engineering Handbook

Production-grade rules, skills, commands, and MCP server for AI coding agents - language, cloud, security, and AI/ML standards for 15+ stacks

License: MIT

Comprehensive, battle-tested configuration for AI coding agents. Curated rules (.mdc), Agent Skills, a skill evaluation harness, slash commands, an MCP server, and lifecycle hooks covering languages, cloud platforms, DevOps tools, data platforms, identity systems, AI/ML, Zero Trust, and engineering patterns.

Note

Agent-neutral. Originally built for Cursor; today the content ships in formats compatible with Cursor, Claude Code, and Codex - rules (.cursor/rules/, AGENTS.md), Agent Skills (.cursor/skills/, .claude/skills/, .codex/skills/), and slash commands. The MCP server works with any MCP-compatible client.

Renamed in May 2026 from cursor-engineering-rules to agent-engineering-handbook to reflect what the repo became (rules + skills + commands + MCP server + hooks for any AI coding agent, not just Cursor). GitHub redirects old URLs, so existing clones, submodules, and bookmarks keep working.

What's Included

Core Standards

Programming Languages

  • 200-python.mdc - Python best practices (PEP 8, type hints, async)
  • 210-go.mdc - Go patterns (error handling, concurrency, generics)
  • 230-javascript.mdc - JavaScript/Node.js (ES modules, async/await)
  • 240-typescript.mdc - TypeScript (type safety, advanced types)
  • 260-frontend.mdc - Frontend architecture cross-cutting non-negotiables (SSG/SSR/SPA/ISR choice, bundle budgets, state buckets, WCAG, Core Web Vitals, supply-chain); pairs with the frontend-engineering skill
  • 220-rust.mdc - Rust (ownership, borrowing, async)
  • 140-bash.mdc - Shell scripting (POSIX compliance, safety)

Cloud Platforms

  • 410-aws.mdc - AWS (EKS, VPC Lattice, Zero Trust, IAM)
  • 430-azure.mdc - Azure (Bicep, Key Vault, App Service)
  • 420-gcp.mdc - GCP (Cloud Run, GKE, Secret Manager)
  • 400-cloudflare.mdc - Cloudflare (Workers, Rules Engine, WAF policy)
  • 401-cloudflare-workers.mdc - Cloudflare Workers TypeScript non-negotiables (file-scoped to wrangler.jsonc + Worker entry files)
  • 405-cloudflare-waf-rules.mdc - Cloudflare WAF rule tactical playbook for Terraform / Dashboard / API authoring (source-of-truth discipline, predicates, guards, per-interface provenance + checklist)

AI & Machine Learning

DevOps & Infrastructure

Security & Testing

Patterns & Best Practices

Utilities

Scripts

Utility scripts for Cursor maintenance:

# Preview cleanup
./scripts/cursor-maintenance.sh --dry-run

# Run cleanup
./scripts/cursor-maintenance.sh

See scripts/README.md for details.

Hooks (optional)

Deterministic lifecycle hooks to observe/control agent behavior (for example: gate destructive shell commands, block reading .env files).

Slash Commands

Workflow commands for explicit phase transitions. Type /command in your agent's chat (Cursor / Claude Code / Codex) to trigger.

Command Purpose
/init Initialize task - analyze project, detect complexity
/plan Enter planning phase - analyze, design, document approach
/creative Enter creative phase - explore design options for complex tasks
/qa Run QA validation - check dependencies, config, environment
/build Enter implementation phase - write code following approved plan
/review Enter review phase - verify implementation, suggest improvements
/self-review Comprehensive local PR review (compare branch to main)
/quick-review Fast critical issues check (pre-commit validation)
/check-progress Review work progress, propose commit message
/archive Archive task - document lessons learned, update knowledge base

Installation:

# Copy to your project
cp -r /path/to/agent-engineering-handbook/commands .cursor/commands

# Or symlink
ln -s /path/to/agent-engineering-handbook/commands .cursor/commands

Workflow:

Simple:   /init -> /build -> /review
Moderate: /init -> /plan -> /qa -> /build -> /review
Complex:  /init -> /plan -> /creative -> /qa -> /build -> /review -> /archive

See commands/README.md for detailed documentation.

MCP Server

Model Context Protocol (MCP) server for any MCP-compatible AI client (Cursor, Claude Desktop, Claude Code, Codex, and others).

# Install
cd mcp/cursor-rules-mcp
npm install
npm run build
npm link

# Configure Claude Desktop
# Add to ~/Library/Application Support/Claude/claude_desktop_config.json:
{
  "mcpServers": {
    "agent-engineering-handbook": {
      "command": "cursor-rules-mcp"
    }
  }
}

Features:

  • Fetch workflow guide (Plan/Implement/Review)
  • Fetch specific rules by category/topic
  • List all available rules
  • Just-in-time rule loading (load only what you need)

See mcp/cursor-rules-mcp/README.md for full documentation.

Configuration Approaches

Cursor supports two ways to load rules. Choose based on your needs:

Approach A: Frontmatter-based (No .cursorrules needed)

Rules with alwaysApply: true in their frontmatter load automatically when placed in .cursor/rules/.

Best for: Personal setup, global rules across all projects

# Symlink to your home directory (applies to all projects)
mkdir -p ~/.cursor
ln -s /path/to/agent-engineering-handbook/rules ~/.cursor/rules

# Or symlink per-project
mkdir -p .cursor
ln -s /path/to/agent-engineering-handbook/rules .cursor/rules

Rules that auto-load (alwaysApply: true):

Rule Purpose
010-workflow.mdc Plan/Implement/Review workflow
015-context-engineering.mdc Prompt packing, retrieval, compaction
020-agent-audit.mdc Agent audit requirements
100-core.mdc Core coding standards
110-configuration.mdc Configuration management
120-utilities.mdc CLI tools
130-git.mdc Git conventions and signed commits
310-security.mdc Security best practices
316-zero-trust.mdc Distinguished Engineer - Zero Trust
800-markdown.mdc Markdown formatting

Other rules load based on file patterns or explicit request.

Approach B: Explicit .cursorrules file

Use a .cursorrules file for explicit control over which rules load.

Best for: Team projects, project-specific subsets, version-controlled config

# .cursorrules - Option 1: Load all rules from directory
rulesDirectory: .cursor/rules

# .cursorrules - Option 2: Explicit rule list
rules:
  - .cursor/rules/100-core.mdc
  - .cursor/rules/200-python.mdc
  - .cursor/rules/410-aws.mdc

Note

When using .cursorrules, rules with alwaysApply: true still load automatically in addition to your explicit list.

See examples/.cursorrules-example for tech-stack templates.

Multi-Repo Workspaces

For workspaces with many repositories, rules load based on file patterns. Open a .py file and Python rules load; open a .go file and Go rules load. Most repos need zero per-repo configuration.

See Multi-Repo Workspaces for detailed guidance.

Quick Start

Option 1: Use Individual Rules

Copy specific rules to your project:

# Create Cursor rules directory
mkdir -p .cursor/rules

# Copy specific rules you need
cp path/to/agent-engineering-handbook/rules/200-python.mdc .cursor/rules/
cp path/to/agent-engineering-handbook/rules/410-aws.mdc .cursor/rules/

# (Optional) Copy workflow templates (tasks, active-context, etc.)
mkdir -p .cursor/rules/templates
cp path/to/agent-engineering-handbook/rules/templates/*.template .cursor/rules/templates/

Option 1.5: Use Setup Scripts (Convenience)

If you keep a shared checkout of this repo, you can bootstrap a workspace with:

/path/to/agent-engineering-handbook/setup-workspace.sh -S -l .

Add to your .cursorrules file:

rules:
  - .cursor/rules/200-python.mdc
  - .cursor/rules/410-aws.mdc

Option 2: Use All Rules (Recommended)

Symlink the entire rules directory:

# From your project root
ln -s /absolute/path/to/agent-engineering-handbook/rules .cursor/rules

Configure .cursorrules:

# Load all rules
rulesDirectory: .cursor/rules

# Or be selective with alwaysApply rules
rules:
  - .cursor/rules/100-core.mdc
  - .cursor/rules/200-python.mdc
  - .cursor/rules/310-security.mdc

Option 3: Cherry-Pick by Technology

Create a custom .cursorrules that includes only relevant rules:

# Python + AWS project
rules:
  - .cursor/rules/100-core.mdc
  - .cursor/rules/130-git.mdc
  - .cursor/rules/200-python.mdc
  - .cursor/rules/410-aws.mdc
  - .cursor/rules/180-terraform.mdc
  - .cursor/rules/310-security.mdc
  - .cursor/rules/300-testing.mdc

Rule Priorities

Rules have alwaysApply flags and priority levels:

  • Always Apply: Core standards (100-core, 130-git, 310-security)
  • High Priority: Language-specific rules for your stack
  • Medium Priority: Platform/tool-specific rules
  • Low Priority: Documentation and utility guides

See rules/INDEX.md for complete categorization.

Features

Production Quality

  • Battle-tested patterns from real-world projects
  • Security-first approach (OWASP Top 10, secret scanning)
  • Performance-focused (benchmarks, optimization patterns)

Comprehensive Coverage

  • 6 programming languages (Python, Go, TypeScript, JavaScript, Rust, Bash)
  • 4 major cloud platforms (AWS, Azure, GCP, Cloudflare)
  • 10+ DevOps tools (Terraform, K8s, Docker, Ansible, Helm, GitHub Actions)
  • AI/ML integration (OpenAI, Claude, Bedrock, Vertex AI)

Code Examples

  • Real-world examples for every pattern
  • Good vs Bad comparisons
  • Common mistakes and anti-patterns
  • Quick reference sections

Modern Standards

  • Latest versions (Python 3.14+, Go 1.25+, Node 22+)
  • Modern patterns (async/await, generics, type safety)
  • Current tools (ripgrep, fd, fzf, just, jq)

Customization

Workspace-Specific Overrides

Use 999-local-overrides.mdc for project-specific rules:

# Copy to your project
cp rules/999-local-overrides.mdc .cursor/rules/999-local-overrides.mdc

# Edit to add project-specific rules
vim .cursor/rules/999-local-overrides.mdc

Creating Custom Rules

Follow the standard format:

---
title: My Custom Rule
description: Project-specific patterns
priority: 900
alwaysApply: false
files:
  include:
    - "**/*.py"
---

# My Custom Rule

## Pattern 1
[Your custom patterns here]

Contributing

Contributions are welcome! Please see .github/CONTRIBUTING.md for guidelines.

Areas for Contribution

  • Additional language support (Java, C#, Ruby, PHP)
  • More cloud platform patterns
  • Industry-specific patterns (fintech, healthcare, etc.)
  • Performance benchmarks
  • Additional code examples

License

MIT License - see LICENSE for details.

Acknowledgments

This project was inspired by and incorporates patterns from:

Thanks to @DaKaZ for suggesting the commands-based workflow approach.

Related Projects

  • dotcursorrules.com - Community directory of framework-specific cursor rules (Next.js, Laravel, React, etc.). Use dotcursorrules for framework recipes and this repo for engineering discipline.
  • ACE-FCA - Advanced Context Engineering for Coding Agents. Excellent methodology on context management, "frequent intentional compaction", and Research -> Plan -> Implement workflows.
  • Cursor Memory Bank - Command-based workflow system using Cursor's /commands feature for progressive rule loading.
  • Shellwright - Playwright for the shell. MCP server for terminal automation, screenshots, and GIF recording. Excellent example of MCP server implementation with PTY session management.
  • eslint-config-airbnb - JavaScript style guide
  • google-styleguides - Google's style guides
  • uber-go-guide - Uber's Go style guide

Note

Three Ways to Load Context: This repo supports multiple approaches:

  1. Rules (.mdc files) - Auto-load based on alwaysApply flags and file patterns
  2. Commands (/plan, /build, etc.) - Explicit phase transitions for progressive disclosure
  3. MCP Server - On-demand rule loading via tool calls

Use all three together for maximum flexibility, or pick what works for your workflow.

Cursor rules vs Cursor skills

Based on Cursor's docs:

  • Cursor Rules (docs)

    • What they are: System-level instructions included at the start of model context to provide persistent guidance
    • Where they live: typically .cursor/rules/ (project, version-controlled), plus User Rules (global) and Team Rules (dashboard). Also AGENTS.md as a simpler alternative
    • How they apply: always apply, agent decides, file-glob scoped, or manual @ mention
    • Best for: coding standards, architectural constraints, security guardrails, "do/don't", house style

  • Cursor Skills / Agent Skills (docs)

    • What they are: portable, version-controlled packages that teach an agent a domain-specific workflow; may include executable scripts the agent runs
    • Where they live: .cursor/skills/ (project) or ~/.cursor/skills/ (user). Cursor also discovers .claude/skills/ and .codex/skills/ for compatibility
    • How they apply: the agent can auto-select a relevant skill, or you can invoke it manually via /skill-name. You can force "manual only" by setting disable-model-invocation: true
    • Best for: repeatable multi-step playbooks (release, deploy, migration, audit, generating artifacts) and "do X end-to-end" flows

Practical comparison (the parts that bite in YAML)

The bullets above orient; this table is the reference for "what do I put in the frontmatter, and what is it going to cost me at runtime?"

Rules (.mdc) Skills (SKILL.md)
Frontmatter fields title, description, priority, alwaysApply, files.include name, description, optionally disable-model-invocation
alwaysApply honored? Yes - core mechanism No - not in the skills schema; silently ignored
Activation triggers alwaysApply: true (every conversation), files.include glob (when matching file opens), or agent-selected Agent reads description and self-selects; user runs /skill-name
Cost of being "always on" A few hundred tokens per conversation - fine Entire SKILL.md + references loaded per conversation - token explosion + agent confusion
How to get "always-on" semantics for skill-domain content Put the principles in a rule (with alwaysApply: true); leave the workflow in a skill. Many domains in this repo do both - 316-zero-trust.mdc + skills/zero-trust/; 260-frontend.mdc + skills/frontend-engineering/; 325-networking.mdc + skills/networking-transport/ n/a (do not try)

Short answer to "should this skill have alwaysApply: true?": no. If the content needs to be loaded every conversation, lift the principles into a rule and keep the playbook in the skill.

Skills shipped in this repo

Skills under skills/ cover repeatable end-to-end workflows that pair with the rules above. Cursor auto-selects them based on the SKILL.md description: triggers; invoke manually as /<skill-name> when needed.

Engineering & code

Security & identity

Cloud, data & infrastructure

AI, MCP & analysis

Documentation & artifacts

Workflow patterns (meta)

Evaluating Skills

The dependency-free Agent Skills eval harness validates every skill and supports with-skill versus baseline comparisons through a vendor-neutral command adapter. Pull-request CI runs deterministic schema and unit checks without model credentials or paid calls.

The initial suites cover:

uv run python -m evals.skill_eval validate
uv run python -m unittest discover -s evals/tests -v

See the eval documentation for the adapter protocol, deterministic checks, model-backed runs, artifacts, safety limits, and expansion criteria.

About

Engineering handbook for AI coding agents - rules, skills, slash commands, MCP server, and hooks for Cursor, Claude Code, and Codex

Resources

Readme
MIT license

Contributing

Contributing
Activity

Stars

15 stars

Watchers

0 watching

Forks

2 forks
Report repository

Releases

Packages

Contributors

Languages