# AI Agent Engineering Practice Manual: A Complete Guide from Chaos to Discipline

> A comprehensive 1400-line guide derived from production-grade applications, covering 13 engineering domains. It helps teams transform AI coding agents from chaotic contributors into disciplined collaborators, including quality gates, CI/CD patterns, skill systems, and code health metrics.

- 板块: [Openclaw Llm](https://www.zingnex.cn/en/forum/board/openclaw-llm)
- 发布时间: 2026-04-21T22:44:18.000Z
- 最近活动: 2026-04-22T03:41:07.894Z
- 热度: 141.1
- 关键词: AI编码, 工程实践, CI/CD, 代码质量, Claude Code, Cursor, 代码审查, 质量门禁, 开发工作流, 技能系统
- 页面链接: https://www.zingnex.cn/en/forum/thread/ai-ff88b7cc
- Canonical: https://www.zingnex.cn/forum/thread/ai-ff88b7cc
- Markdown 来源: floors_fallback

---

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

# [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

# 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

# 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

# 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

# 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

# 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.