convez.ai
MCP ServerProdutividadeAvançado
d-padmanabhan

Agent Engineering Handbook

d-padmanabhan/agent-engineering-handbook

Rules, skills e MCP server para engenharia de software assistida por IA

Ver no GitHub
BomPluginScore · de 0 a 100

Handbook 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-handbook

1 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

Estrelas
20
Forks
3
Acompanhando
1
Saúde
71%
Último commit
há 1 semana
Versão
—
Issues abertas
1
Contribuidores
2

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.

License: MIT

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

  1. Clone or update this repository.
  2. Resolve the checkout's absolute path.
  3. Link each handbook surface into its matching Cursor user directory.
  4. Run the repository's setup or validation commands.
  5. 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.

ConcernRulesSkills
PurposeMandatory constraints and routingWorkflows, examples, references, and procedures
Typical location.cursor/rules/*.mdc.cursor/skills/*/SKILL.md or .agents/skills/*/SKILL.md
SelectionalwaysApply, globs, description-based selection, or explicit useAutomatic selection or /skill-name
Context costKeep concise, especially when always appliedLoad only when the task matches
Repository policyOne canonical owner for each mandatory gateRoute to the owning rule instead of duplicating policy

Other supported instruction surfaces include:

  • root or nested AGENTS.md files;
  • 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.

CommandPurpose
/initInitialize work and classify complexity
/planDesign an implementation before editing
/creativeExplore alternatives for complex design decisions
/qaValidate dependencies, configuration, and environment
/buildImplement an approved plan
/reviewReview completed implementation
/self-reviewReview local branch changes against the base
/quick-reviewRun a focused critical-issue review
/check-progressFix clear issues and summarize progress
/code-commitRun the controlled commit and push workflow with approval gates
/archiveRecord lessons and archive completed complex work
/awsApply AWS guidance
/bashApply Bash guidance
/ghaApply GitHub Actions guidance
/goApply Go guidance
/javascriptApply JavaScript and TypeScript guidance
/markdownApply Markdown guidance
/pythonApply Python guidance
/terraformApply 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

Security and Identity

Cloud and Infrastructure

Data, AI, and Documentation

Skill Catalog

The repository currently contains 54 skill packages. Each directory listed below contains a SKILL.md.

Engineering and Languages

Security and Identity

Cloud, Infrastructure, and Delivery

Data Engineering

AI and Analysis

Documentation and Artifacts

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:

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:

The command-based workflow was suggested by @DaKaZ.

Related references:

License

Licensed under the MIT License. See LICENSE.

Ver o original no GitHub

Bom para

Relacionados