Agent Engineering Handbook
d-padmanabhan/agent-engineering-handbook
Rules, skills e MCP server para engenharia de software assistida por IA
Ver no GitHubHandbook completo com 52 regras, 54 skills, 19 comandos customizados e 32 suites de avaliação para engenharia de software com agentes IA. Inclui MCP server que expõe regras via Model Context Protocol para Cursor, Claude Code e Codex.
Instalação
npx convez-ai d-padmanabhan/agent-engineering-handbook1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Padronizar comportamento de agentes IA em projetos Cursor
- Implementar workflows determinísticos de desenvolvimento com hooks
- Avaliar e melhorar skills de agentes através de eval suites
- Expor regras de engenharia via MCP para Claude e outras ferramentas
Veredito

Recurso maduro e altamente estruturado para equipes que usam Cursor + agentes IA em produção. Exige integração manual com setup de symlinks, mas oferece cobertura profunda em design, segurança, cloud e infraestrutura.
README
A tradução para o português deste README ainda está na fila.
Agent Engineering Handbook
Rules, Agent Skills, commands, hooks, evaluation tooling, and an MCP server for AI-assisted software engineering.
This repository contains 52 Cursor rule files, 54 Agent Skills, 19 custom Cursor commands, and 32 behavioral eval suites covering software design, languages, cloud platforms, infrastructure, security, identity, data, AI systems, and documentation.
The content is organized for progressive disclosure:
- Rules provide concise mandatory gates that apply automatically, by file scope, or when selected.
- Skills provide detailed workflows, examples, references, and verification procedures.
- Commands provide manually invoked Cursor workflows.
- Hooks provide deterministic checks around agent activity.
- Evals measure whether skills improve behavior.
- The MCP server exposes handbook rules through the Model Context Protocol.
Contents
- Start Here
- Rules and Skills
- Install for Cursor
- Custom Commands
- Hooks
- MCP Server
- Rule Highlights
- Skill Catalog
- Skill Evaluation
- Repository Utilities
- Contributing
- License
Start Here
- Clone or update this repository.
- Resolve the checkout's absolute path.
- Link each handbook surface into its matching Cursor user directory.
- Run the repository's setup or validation commands.
- Keep project-specific exceptions in the target repository rather than modifying shared handbook policy.
From the handbook checkout, resolve the absolute source path:
cd "/absolute/path/to/agent-engineering-handbook"
export HANDBOOK_ROOT="$(pwd -P)"
mkdir -p "${HOME}/.cursor"
On a new Cursor installation, link each repository directory to the corresponding Cursor user path:
ln -s "${HANDBOOK_ROOT}/rules" "${HOME}/.cursor/rules"
ln -s "${HANDBOOK_ROOT}/skills" "${HOME}/.cursor/skills"
ln -s "${HANDBOOK_ROOT}/commands" "${HOME}/.cursor/commands"
ln -s "${HANDBOOK_ROOT}" "${HOME}/.cursor/agent-engineering-handbook"
The first three links make rules, skills, and commands discoverable in their actual Cursor home locations. The final stable-root link supports portable ${HANDBOOK_ROOT}/... references used inside handbook content. Before running these commands, confirm that none of the destination paths already contains user configuration. Use the merge-safe installation below when a destination already exists.
Rules and Skills
Cursor project rules live under .cursor/rules/. Current rule activation fields are description, globs, and alwaysApply. This repository also uses title and numeric priority as catalog metadata; do not assume Cursor uses them for activation order.
Cursor project skills live in .cursor/skills/ or .agents/skills/; user skills live in ~/.cursor/skills/ or ~/.agents/skills/. Cursor also discovers compatible skill directories used by Claude Code and Codex. This repository's portable skill contract requires name and description.
| Concern | Rules | Skills |
|---|---|---|
| Purpose | Mandatory constraints and routing | Workflows, examples, references, and procedures |
| Typical location | .cursor/rules/*.mdc | .cursor/skills/*/SKILL.md or .agents/skills/*/SKILL.md |
| Selection | alwaysApply, globs, description-based selection, or explicit use | Automatic selection or /skill-name |
| Context cost | Keep concise, especially when always applied | Load only when the task matches |
| Repository policy | One canonical owner for each mandatory gate | Route to the owning rule instead of duplicating policy |
Other supported instruction surfaces include:
- root or nested
AGENTS.mdfiles; - local User Rules under
~/.cursor/rules; - account-synced User Rules configured in Cursor;
- Team Rules managed through the Cursor dashboard.
The legacy .cursorrules file is still recognized during migration but is marked for deprecation. Do not use the undocumented rulesDirectory or rules: YAML shapes previously shown by this README. Migrate legacy content to .cursor/rules/*.mdc, AGENTS.md, or Agent Skills.
Current Cursor references:
Install for Cursor
Merge-Safe User Installation
If ~/.cursor/rules, ~/.cursor/skills, or ~/.cursor/commands already exists, preserve it and link individual handbook entries:
cd "/absolute/path/to/agent-engineering-handbook"
export HANDBOOK_ROOT="$(pwd -P)"
mkdir -p "${HOME}/.cursor/rules" \
"${HOME}/.cursor/skills" \
"${HOME}/.cursor/commands"
shopt -s nullglob
for source in "${HANDBOOK_ROOT}"/rules/*.mdc; do
destination="${HOME}/.cursor/rules/$(basename "${source}")"
test -e "${destination}" || test -L "${destination}" || ln -s "${source}" "${destination}"
done
for source in "${HANDBOOK_ROOT}"/skills/*; do
if [[ ! -f "${source}/SKILL.md" ]]; then
continue
fi
destination="${HOME}/.cursor/skills/$(basename "${source}")"
test -e "${destination}" || test -L "${destination}" || ln -s "${source}" "${destination}"
done
for source in "${HANDBOOK_ROOT}"/commands/*.md; do
if [[ "$(basename "${source}")" == "README.md" ]]; then
continue
fi
destination="${HOME}/.cursor/commands/$(basename "${source}")"
test -e "${destination}" || test -L "${destination}" || ln -s "${source}" "${destination}"
done
Existing destinations are left unchanged. Review any skipped name collision manually; do not overwrite unrelated user configuration.
Bootstrap a Project Workspace
The setup script creates workspace context files and can link the repository's rule directory into a target workspace:
"${HANDBOOK_ROOT}/setup-workspace.sh" \
--symlink-all \
--lightweight \
--ensure-gitignore \
.
This symlink layout is a handbook convention for local workspaces. Cursor documentation explicitly supports skill discovery through symlinked directories, but does not guarantee every rule-symlink topology. If rule discovery does not work in the installed Cursor version, use the copy fallback below.
Option 2: Copy Rules into a Project
Copy all rules:
mkdir -p .cursor/rules
cp "${HANDBOOK_ROOT}/rules/"*.mdc .cursor/rules/
Or copy only the rules required by the project:
mkdir -p .cursor/rules
cp "${HANDBOOK_ROOT}/rules/100-core.mdc" .cursor/rules/
cp "${HANDBOOK_ROOT}/rules/200-python.mdc" .cursor/rules/
cp "${HANDBOOK_ROOT}/rules/310-security.mdc" .cursor/rules/
Copy the files again when the handbook changes, or automate a reviewed synchronization process.
Install Skills
The Cursor CLI changelog documents skill discovery through symlinked directories:
mkdir -p .cursor
ln -s "${HANDBOOK_ROOT}/skills" .cursor/skills
Copying is the portable fallback:
mkdir -p .cursor/skills
cp -R "${HANDBOOK_ROOT}/skills/." .cursor/skills/
For Codex-native project discovery, use .agents/skills/. Claude Code commonly uses .claude/skills/. Verify client-specific installation and precedence against current vendor documentation.
Create a Project Rule
Use supported file-scoped frontmatter:
---
description: Python API conventions for this project
globs:
- "src/api/**/*.py"
alwaysApply: false
---
# Python API Conventions
- Validate request data before policy or business logic.
- Keep project-specific exceptions narrow and documented.
Place the file under .cursor/rules/, for example .cursor/rules/python-api.mdc.
Custom Commands
The commands/ directory contains 19 Cursor custom command files. Copy them only when command-based workflows are desired:
mkdir -p .cursor
cp -R "${HANDBOOK_ROOT}/commands" .cursor/commands
Cursor still supports .cursor/commands, but reusable commands can be migrated to manually invoked Agent Skills with /migrate-to-skills. Names such as /plan and /review can collide with Cursor built-ins; confirm the selected command in the UI or rename the local file.
| Command | Purpose |
|---|---|
/init | Initialize work and classify complexity |
/plan | Design an implementation before editing |
/creative | Explore alternatives for complex design decisions |
/qa | Validate dependencies, configuration, and environment |
/build | Implement an approved plan |
/review | Review completed implementation |
/self-review | Review local branch changes against the base |
/quick-review | Run a focused critical-issue review |
/check-progress | Fix clear issues and summarize progress |
/code-commit | Run the controlled commit and push workflow with approval gates |
/archive | Record lessons and archive completed complex work |
/aws | Apply AWS guidance |
/bash | Apply Bash guidance |
/gha | Apply GitHub Actions guidance |
/go | Apply Go guidance |
/javascript | Apply JavaScript and TypeScript guidance |
/markdown | Apply Markdown guidance |
/python | Apply Python guidance |
/terraform | Apply Terraform guidance |
Typical workflow:
Simple: /init -> /build -> /review
Planned: /init -> /plan -> /qa -> /build -> /review
Complex: /init -> /plan -> /creative -> /qa -> /build -> /review -> /archive
See the command reference for installation details and command-specific behavior.
Hooks
Cursor hook configuration locations include:
- project hooks:
.cursor/hooks.json; - user hooks:
~/.cursor/hooks.json.
Install the optional local hook pack:
./scripts/cursor-hooks-install.sh --project .
The hook pack gates selected destructive shell behavior and records bounded audit events. Review the generated configuration and scripts before enabling them in another repository.
See the hooks guide and Cursor hook pack.
MCP Server
The repository includes a local stdio MCP server that exposes handbook rules. Build and link it:
cd mcp/cursor-rules-mcp
npm install
npm run build
npm link
Configure Cursor in .cursor/mcp.json or ~/.cursor/mcp.json:
{
"mcpServers": {
"agent-engineering-handbook": {
"command": "cursor-rules-mcp",
"env": {
"CURSOR_RULES_PATH": "/absolute/path/to/agent-engineering-handbook/rules"
}
}
}
}
Claude Desktop uses the same server definition inside ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"agent-engineering-handbook": {
"command": "cursor-rules-mcp",
"env": {
"CURSOR_RULES_PATH": "/absolute/path/to/agent-engineering-handbook/rules"
}
}
}
}
The server currently uses a maintained topic map rather than automatic filesystem discovery. Update and test that map when rules are added or renamed.
See the MCP server reference for tools, development commands, and troubleshooting.
Rule Highlights
The repository currently contains 52 .mdc rule files. The following list highlights common entry points; the rule index is authoritative.
Workflow and Core Engineering
Languages and Application Design
- Bash
- Python
- Go
- Rust
- JavaScript and TypeScript
- Frontend
- API design
- Networking
- Observability, with detailed workflows in the observability skill
Security and Identity
Cloud and Infrastructure
- GitHub Actions
- CloudFormation
- Terraform
- Ansible
- Cloudflare
- AWS
- Google Cloud
- Azure
- Docker
- Kubernetes
- Helm
Data, AI, and Documentation
- PostgreSQL
- SQL
- Data engineering
- Databricks
- Snowflake
- Kafka
- Teradata
- AI and machine learning
- MCP servers
- Markdown and generated PNG diagrams
- Documentation
- Open source
Skill Catalog
The repository currently contains 54 skill packages. Each directory listed below contains a SKILL.md.
Engineering and Languages
- Agent workflow
- API design
- Bash shell scripting
- Core engineering
- Distributed transactions
- Domain-Driven Design
- Frontend engineering
- Git workflow
- Go and Rust systems
- Networking and transport
- Observability
- Python development
- Scripting automation
- Service resilience
- System design
- TypeScript and JavaScript
Security and Identity
- AWS IAM
- Codebase security audit
- IAM security advisor
- Okta
- Security testing
- Workload identity
- Zero Trust
Cloud, Infrastructure, and Delivery
- Agents SDK
- CI/CD with GitHub Actions
- Cloud platforms
- Cloudflare
- Cloudflare email service
- Cloudflare WAF authoring
- Cloudflare Workers authoring
- Containers and orchestration
- Durable Objects
- Infrastructure as Code
- Kubernetes and containers
- Kubernetes operator development
- Sandbox SDK
- Workers best practices
- Wrangler
Data Engineering
AI and Analysis
Documentation and Artifacts
- Documentation standards and generated PNG diagrams
- PDF export
- React Flow architecture diagrams
- Single-file dashboard
- Web performance
Skill Maintenance
Skill Evaluation
The dependency-free Agent Skills eval harness validates all skill metadata and the 32 available behavioral suites. Model-backed comparisons use an external command adapter; pull-request CI runs deterministic validation and unit tests without model credentials.
Current behavioral suites:
- Agent workflow
- API design
- AWS IAM
- Bash shell scripting
- CI/CD with GitHub Actions
- Cloudflare WAF authoring
- Cloudflare Workers authoring
- Containers and orchestration
- Core engineering
- Data engineering
- PostgreSQL
- Documentation standards
- Domain-Driven Design
- Distributed transactions
- Git workflow
- Go and Rust systems
- IAM security advisor
- Independent verification
- Kubernetes and containers
- Kubernetes operator development
- Memory architecture
- Networking and transport
- Observability
- Okta
- Python development
- Scripting automation
- Security testing
- Service resilience
- System design
- TypeScript and JavaScript
- Workload identity
- Zero Trust
Run deterministic validation:
uv run python -m evals.skill_eval validate
uv run python -m unittest discover -s evals/tests -v
See the eval harness documentation for adapter limits, paired comparisons, output redaction, and artifact handling.
Repository Utilities
Preview and run Cursor cache cleanup:
./scripts/cursor-maintenance.sh --dry-run
./scripts/cursor-maintenance.sh
Run repository checks:
pre-commit run --all-files
uv run python -m evals.skill_eval validate
uv run python -m unittest discover -s evals/tests -v
Current runtime and toolchain requirements are owned by the relevant rule or skill and should be verified against the deployment target before adoption. Do not treat a version number in this README as an evergreen recommendation.
Contributing
Contributions should keep mandatory rules concise, place procedures and examples in skills, update affected evals, and preserve safe runnable examples. See the contribution guide.
Acknowledgments
The repository drew ideas from:
- AI Developer Guide for workflow and context-management patterns;
- Cursor Memory Bank for progressive context files;
- Shellwright for terminal automation and PTY-oriented MCP patterns.
The command-based workflow was suggested by @DaKaZ.
Related references:
- Advanced Context Engineering for Coding Agents
- Airbnb JavaScript Style Guide
- Google Style Guides
- Uber Go Style Guide
License
Licensed under the MIT License. See LICENSE.