Agent_Engineering_Kit：面向 Codex、Claude Code 和 Cursor 的 AI 编码智能体工程规范库

Engineering standards, project instructions, and workflows for AI coding agents.

Agent_Engineering_Kit is a reusable library for guiding coding agents in Codex, Claude Code, and Cursor. It brings together architecture and coding rules, proportionate verification, project documentation templates, and configurable agent roles. Adopt the resources that match your project's stack in a new or existing workspace.

The library consists of Markdown instructions, a TOML catalog, and inactive configuration and skill templates. A Python checker and its tests support source maintenance. Adoption happens through an agent following the integration procedure; no package installation, dedicated CLI, or application runtime is required.

What it provides

• Shared engineering standards: responsibility boundaries, domain invariants, explicit contracts, practical abstractions, and limits on speculative code.
• Technology profiles: focused guidance for backend, frontend, persistence, containers, and Unreal Engine projects, with topic sections and examples.
• Project entry points: short AGENTS.md instructions that route agents to relevant rules, architecture, and planning documents.
• Delivery and verification policies: small logical stages, human checkpoints, checks chosen for the affected behavior, and reuse of still-valid evidence.
• Optional agent orchestration: selected roles, model/reasoning-effort pairs, permitted delegation relationships, and concurrency limits.
• An adoption procedure: preparation, import, updates, conflict resolution, provenance tracking, and recovery that preserves local changes.

Rules, templates, and this README are written in English. The shared language policy calls for English analysis, working notes, specifications, and plans, while user-facing communication follows the user's language. An explicit request for a different response or artifact language takes precedence for that material.

Getting started

Keep an accessible copy of this library and identify the target project and one client: Codex, Claude Code, or Cursor. You can ask the agent to read the integration skill directly from the source; global skill installation is unnecessary.

To preview adoption, replace the placeholders in this request:

Read templates/skills/aek-integrate-project/SKILL.md from the Agent_Engineering_Kit source at <framework-path>. For the project at <project-path> using <client>, prepare an import of the applicable rules. Show the proposed file changes and conflict resolutions. Leave the target project untouched.

Preparation produces a concrete change set: selected profiles, destination paths, proposed contents, retained local constraints, conflict decisions, and checks. It creates no files or adoption record in the target project.

To apply a reviewed proposal:

Apply the prepared Agent_Engineering_Kit import to <project-path> for <client> within the reviewed scope. Preserve unrelated changes and existing model choices, and follow the agreed checkpoints.

An explicit import request can already authorize the relevant changes; the procedure reuses that authorization. Model setup has its own scope.

The integration skill follows MIGRATION.md, which defines the full procedure:

1. Inspect the actual stack, active instructions, local contracts, and client capabilities. For a new project, record the intended architecture as proposed.
2. Select profiles from the catalog, including shared required policies and the selected profiles' dependencies and resources. New imports put standards/ and inactive templates/ under .agents-framework/; root project documents and active native files retain their agreed locations.
3. Adapt entry and architecture templates. Reconcile conflicting instructions in the files the client actually loads while preserving required project checks.
4. Apply the authorized changes, retaining originals and accounting for edits made since preparation.
5. Validate the adopted references and record the import in .agents-framework/adoption.md, using the adoption record template.

The adoption record tracks source identity, managed files or sections, accepted contents, exceptions, and recovery information. Updates compare these with local changes. Read this record for import, update, or recovery; task progress and model assignments retain their own documents. Keep the framework source accessible for future updates.

The source library layout stays unchanged. Existing flat imports remain supported; an ordinary update does not relocate them. For a selected move, follow the layout and relocation contract, preserving local edits and immutable old accepted snapshots. Portable optional source routes use known URLs or labelled source paths through provenance, not author-machine links.

Choose rules by the actual stack

Start with the affected concern and the relevant profile. A combined profile applies only the components used in the project: Python does not imply FastAPI, React does not imply Next.js or TypeScript, and Angular does not imply NgRx.

The catalog guide distinguishes bundling from reading. The required, dependencies, and resources fields determine which files remain available in an adopted bundle. The task, actual stack, and when conditions determine what the agent reads. Availability does not require loading every profile, example, research note, or historical plan into each session.

For new imports, select the language and the hosts, frameworks or libraries actually used. TypeScript composes with React, Next.js, Node.js, NestJS, Angular and other technologies through one shared profile. The five older combined IDs remain compatibility aggregates; see profile selection.

These profiles contain opinionated project standards. Numeric size limits, layering preferences, and testing policies are local engineering choices; references to technology documentation do not make them universal requirements. Apply guidance against the target project's actual versions and architecture.

For example, the Doctrine and TypeORM guidance makes domain-model placement an explicit project decision. Angular and NgRx guidance selects state ownership and reactivity tools by the feature's needs. Docker guidance covers both dependency-only Compose setups and containerized applications, including development/production separation.

Unreal uses an engine and editor model: lifecycle, reflection, garbage collection, assets, unsaved editor state, and cooking affect how the shared principles apply. Its topic resources are listed in the catalog and read by task. Blueprint-only work does not require C++, source changes do not require MCP, and backend service patterns are not mandatory gameplay architecture. Blender-to-Unreal work verifies the relevant import result in the engine. See the Unreal profile for the applicable routes and checks.

Working model

Small stages and explicit checkpoints

The default work mode uses the current project directory. The agent completes one small logical stage, runs the necessary checks, reports its result, and pauses for human review. Routine work does not create commits, stage files, create branches or worktrees, or stash changes.

Autonomous worktree execution can be selected explicitly. Permission for commits, integration, push, and pull requests is handled separately. Cleanup follows an approved successful merge and checks that changes have been preserved; branch deletion, push, and deployment need their own authorization.

Verification proportional to the change

The verification policy chooses checks for the affected behavior and its risks while retaining mandatory project and CI gates. Documentation changes normally need artifact checks; executable examples or behavior changes may need focused tests.

Checks run together at the boundary selected by verification.timing under policy configuration. Earlier checks are appropriate for reproducing a bug, resolving a concrete uncertainty, validating a risky dependency, selected TDD, or a required gate. After a fix, rerun affected checks and reuse results whose inputs remain valid. Keep summaries compact and retain detailed failure logs separately.

Shared policy defaults own cadence/review choices, size-review thresholds and soft instruction-length ranges. An adopted project may provide sparse overrides at .agents-framework/policy.toml; absence needs no setup. The checker validates schema and merged constraints. These settings preserve mandatory checks, acceptance and permissions; they are not model configuration or limits on test/review counts.

Architecture and plans with clear ownership

In an adopted workspace:

Preserve existing OpenSpec, Spec Kit, or other supported task stores in their canonical locations, including inside nested projects. Keep decisions and progress in one authoritative place. Changing the implementation checkout or using a worktree does not move the task's owner. A small edit needs no separate plan file.

Independently opened repositories need reachable local instructions and selected rules. Use the root entry, local addition, project architecture, and workspace architecture templates as needed. The planning policy and task contract cover substantive work.

Optional delegation and model configuration

Ordinary work can proceed inline with the current agent when no routing profile is configured. Model setup is triggered by a request or a missing choice needed for necessary delegation; having a plan or a role template does not require subagents.

The model configuration policy defines .agents-framework/model-routing.toml. Version 2 records the client, enabled roles, model/effort pairs, permitted delegation relationships, and agent limit. Version 1 choices remain readable and migrate during authorized setup or reassignment.

• Single-agent mode: only the coordinator is enabled; specialist roles and delegation relationships are absent, and the framework subagent limit is zero.
• Delegated mode: only selected, enabled roles and permitted relationships may be used, within the saved limit. A disabled reviewer is not replaced by an unnamed worker.

Use the setup skill or reassignment skill for the respective operation, following the orchestration policy. Values in the routing template are unconfigured examples. Saved choices must be reconciled with supported native settings; writing a file does not switch an already-running model. Full integration includes a required model-selection decision: reuse consistent choices, prepare authorized setup, retain an explicit deferral or report an unresolved step. Ordinary coding does not trigger this workflow.

Superpowers integration

For consumer-project work, the optional project-workflows profile supplies aek-design-feature and aek-review-changes through one local reference/output contract. They select the project's relevant technical rules for the current operation while preserving direct routes and its existing task/procedure. They select no technology or model. Both entries are optional and selected explicitly. Implementation follows the ordinary core task route, without a separate skill. Install explicitly selected entries through the existing adoption procedure. Use the selected client's supported skill location and format. Copying an inactive template into the bundle does not install it as a native skill.

The Superpowers policy maps skills to relevant tasks and adapts their workflows to the project's checkpoints, Git permissions, model choices, planning locations, and verification policy. Installing the plugin alone does not activate these adaptations.

When the plugin is absent or a helper is unsuitable, a bounded task can follow its canonical plan directly with the necessary checks and review. Use the compatibility notes when a helper or an installed-version contract needs investigation.

Client integration

The library provides instruction routes and templates for three clients. Verify discovery and supported settings in the selected client and version during adoption.

Ready-made native role examples are currently supplied for Codex. Other client mappings follow the integration procedure and require capability checks. Preserve unrelated settings and roles, and resolve conflicting loaded instructions at their actual locations. A statement that root rules have priority does not change a client's native instruction precedence.

Templates are inactive until adapted and installed. Copying a skill does not prove that the client discovers it, and valid configuration syntax does not prove that the intended model or reasoning effort is active.

Repository map

Agent_Engineering_Kit/
├── AGENTS.md                      # Instructions for maintaining this source library
├── README.md                      # Overview and adoption entry point
├── ARCHITECTURE.md                # Design of this rules library
├── MIGRATION.md                   # Preparation, import, updates, and recovery
├── standards/
│   ├── catalog.toml               # Profiles, dependencies, resources, and templates
│   ├── catalog.md                 # Bundle selection and conditional reading semantics
│   └── ...                        # Shared policies, stack profiles, topics, and examples
├── templates/
│   ├── AGENTS.root.md             # Short workspace entry
│   ├── AGENTS.project.md          # Project-local addition
│   ├── policy-entry.md            # Shared policy entry
│   ├── PLANS.md                   # Planning policy
│   ├── task.md                    # Task contract
│   ├── workspace-architecture.md  # Cross-project map
│   ├── project-architecture.md    # Project passport
│   ├── codex/                     # Inactive native configuration and role examples
│   ├── claude/                    # Policy bridge
│   ├── cursor/                    # Rule route
│   ├── framework/                 # Adoption record and model routing templates
│   └── skills/                    # Integration, model procedures, and optional project tasks
├── examples/                      # Illustrative workspace architecture
├── tools/                         # Read-only instruction artifact checker
├── tests/                         # Regression tests for the maintenance checker
└── docs/
    ├── maintenance/               # Checker usage and executable-example reproduction
    ├── specs/                     # Scope and design decisions
    ├── plans/                     # Implementation and verification records
    └── research/                  # Sources, version context, and evidence limits

The root ARCHITECTURE.md describes this library, and AGENTS.md guides agents maintaining its source. Target-project entry and planning files remain inactive templates; no root PLANS.md or client configuration is installed by this maintenance entry. Target adoption is verified in each target workspace independently.

Library maintenance

Recorded library work covers instruction-framework refinement, project integration, technology profiles, maintenance checks, policy settings, and contained adoption. The records below describe source changes and maintenance checks.

When changing the library, run python3 tools/check_instruction_artifacts.py (Python 3.11+, standard library only) for catalog, local-link, fence and TOML checks. See maintenance verification for scoped commands, checker tests, syntax limits and example reproduction. Also review affected YAML and instruction consistency. Validate executable examples with the relevant stack when their behavior changes. The tests/ directory verifies the maintenance checker; the repository has no standalone framework application or application test suite.