[Introduction] AI Agent Engineering Practice Manual: A Complete Guide from Chaos to Discipline

This comprehensive 1400-line guide, derived from production-grade applications, covers 13 engineering domains. It aims to help teams transform AI coding agents from chaotic contributors into disciplined collaborators. The manual includes key content such as quality gates, CI/CD patterns, skill systems, and code health metrics, providing a complete engineering workflow from agent instruction configuration to the compound growth of debugging knowledge.

Common Dilemmas of AI Coding Tools

Teams using AI coding agents like Claude Code, Cursor, and GitHub Copilot commonly face the "fast but chaotic" problem:

• Inconsistent quality: Code does not follow team conventions; commit messages are random, type annotations are missing, lint errors are overlooked, and architecture violations are hard to clarify;
• No organizational memory: Each session starts from scratch, requiring repeated corrections on branch strategies, test conventions, etc.;
• CI whack-a-mole: Repeatedly fixing CI errors after pushing, disrupting workflow flow;
• Accumulating technical debt: Lack of metric constraints leads to increasing issues like type ignores and lint suppressions;
• Loss of debugging knowledge: Problem-solving experience is not沉淀 (accumulated), leading to repeated mistakes.

Core Solutions: Making AI a Disciplined Collaborator

Key innovations of the manual include:

1. Agent.md (Project Constitution): A root directory file defining rules and conventions, so AI sessions understand project specifications from the first message;
2. Quality Ratchet: Metrics only move forward—if there is regression (e.g., new type: ignore in PR), it must be fixed elsewhere;
3. Local CI = Remote CI: Unify check rules via ci-checks.json, syncing local runners with remote CI;
4. Multi-role Code Review: Five roles (correctness, testing, project standards, etc.) conduct parallel reviews;
5. Compound Learning Loop: Consult experience → capture lessons → promote to rules,沉淀 (accumulate) knowledge.

Ready-to-Use Quick Start Path

Basic Setup (5 minutes)

1. Copy Agent.md to the root directory and edit;
2. Set up the local CI check script;
3. Run python scripts/ci_check_local.py --fix before committing to auto-fix format/lint issues.

Advanced Adoption (hours to days)

• Add code health checks to CI;
• Record the type-ignore threshold;
• Copy commit/code review skills to the project;
• Create a lessons learned document.

Full Adoption (weeks to months)

• Adapt review role conventions;
• Enable PR quality regression checks;
• Set up semantic code navigation tools;
• Add brainstorming skills.

Tech Stack Adaptability: Cross-Stack General Principles

The manual is based on Python/FastAPI + React/TypeScript, but components can be adapted:

Component	Used in This Manual	Alternatives
Python linter/formatter	ruff	black + flake8, pylint
Type checker	mypy	pyright, pytype
Code metrics	radon	wily, complexipy
Duplication detection	jscpd	CPD, Simian
Dead code detection	vulture	pylint unused-import
Dependency check	deptry	pip-extra-reqs
Task queue	SAQ	Celery, Dramatiq, Arq
Migration tool	Alembic	Django migrations, Flyway
Code navigation	Serena (MCP)	—
Agent	Claude Code	Cursor, Copilot, Aider

Value and Significance of the Manual

This manual provides a production-validated complete framework instead of scattered prompts, bringing the following values:

1. Ready-to-use starting point: Based on validated practices, no need to摸索 (explore) from scratch;
2. Progressive path: From 5-minute basic setup to full adoption, adapting to team rhythm;
3. Quality assurance: Quality ratchet and dual CI system ensure AI contributions do not reduce code quality;
4. Knowledge沉淀 (accumulation): The compound learning loop turns experience into reusable rules.

In today's era of rapid AI tool iteration, the manual emphasizes building engineering discipline so any AI tool can collaborate efficiently.