The AI Harness: Why Your AI Coding Agent Is Only as Smart as the Repo You Put It In

1. 理解任务：用户说"帮我把这个 API 从 REST 改成 GraphQL"
2. 探索代码库：找相关的 API 路由、数据模型、测试文件
3. 理解上下文：这个项目用的什么框架？数据库是什么？API 怎么组织的？
4. 写代码：实现 GraphQL 替代 REST
5. 验证：运行测试，确保没有破坏现有功能

# 好的目录结构
src/
├── api/           # API 路由
│   ├── routes/    # 路由定义
│   ├── handlers/  # 处理器
│   └── middleware/  # 中间件
├── models/        # 数据模型
├── services/     # 业务逻辑
├── utils/        # 工具函数
└── __tests__/   # 测试文件（就近放置）

# 不好的目录结构
src/
├── app.js        # 5000 行的 app.js
├── stuff/
├── things/
├── helpers/
└── old/          # 没人知道这目录干嘛的

# 坏的命名
def proc(x, y):
    r = q(x)
    if r > 0:
        return r
    else:
        return 0

# 好的命名
def calculate_discount(original_price, customer_tier):
    discount_amount = compute_discount(customer_tier)
    if discount_amount > 0:
        return discount_amount
    return 0

# 坏的注释：重复代码
def calculate_total(items):
    # 计算总价
    total = 0
    for item in items:
        # 加每个item的价格
        total += item.price
    return total

# 好的注释：解释为什么
def calculate_total(items):
    """
    计算订单总价。

    注意：这里用的是简单的加法，因为目前没有折扣、促销等复杂逻辑。
    如果未来需要支持折扣，请参考 calculate_final_price()。
    """
    return sum(item.price for item in items)

# 好的命名
auth/
├── login_handler.py
├── logout_handler.py
├── register_handler.py
├── token_refresh.py
├── oauth_callback.py
└── auth_middleware.py

# 不好的命名
auth/
├── handler1.py
├── handler2.py
├── util.py      # 又一个 util.py
├── func.py
└── auth.py      # 跟目录同名，但内容不一样？

# AI友善的索引文件：AGENTS.md
# 这个文件告诉 AI agent 代码库的结构和使用方式

# 项目结构
src/
├── api/         # REST API 路由
├── services/     # 业务逻辑层
├── models/      # SQLAlchemy 模型
└── workers/     # 后台任务

# 依赖关系
# api -> services -> models
# workers 使用 services，但不直接调用 models

# 配置
# 环境变量在 .env.example，密码在 .env（不上传）
# 数据库连接需要通过 config.get_database_url()

# 测试
# pytest fixtures 在 tests/conftest.py
# 每个模块有对应的 _test.py 文件
# 运行测试: pytest tests/ -v --cov=src

# 常用命令
# 启动: docker-compose up -d
# 数据库迁移: alembic upgrade head
# 测试: pytest tests/ -v

# 坏的 API 定义
def api_call(data, context):
    """调用 API"""
    return requests.post("http://api.example.com", json=data)

# 好的 API 定义
def send_notification(user_id: str, notification_type: str, message: str) -> dict:
    """
    发送用户通知。

    Args:
        user_id: 用户 ID（必需）
        notification_type: 通知类型，"email" | "sms" | "push"（必需）
        message: 通知内容，最多 500 字符（必需）

    Returns:
        {"success": bool, "message_id": str | None, "error": str | None}

    Raises:
        ValueError: 如果 notification_type 不合法
        httpx.HTTPError: 如果 API 调用失败

    Example:
        >>> result = send_notification("user_123", "email", "Your order shipped!")
        >>> assert result["success"] is True
    """
    if notification_type not in ALLOWED_NOTIFICATION_TYPES:
        raise ValueError(f"notification_type must be one of {ALLOWED_NOTIFICATION_TYPES}")
    return _do_send_notification(user_id, notification_type, message)

# 测试隔离：使用 fixture，不依赖外部状态

import pytest

@pytest.fixture
def test_db():
    """创建测试数据库"""
    db = create_test_database()
    yield db  # 测试在这里运行
    db.cleanup()  # 清理

def test_create_user(test_db):
    """测试创建用户"""
    user = test_db.create_user(email="test@example.com", name="Test")
    assert user.id is not None
    assert user.email == "test@example.com"

# 坏的方式：依赖外部数据库
def test_create_user():
    # 直接连接生产数据库测试
    user = User.create(email="test@example.com", name="Test")
    # 如果数据库里已有这个 email，测试失败
    # 如果测试失败数据没清理，下次运行也会失败

# 好的测试：BDD 风格，描述行为而非实现

def test_user_cannot_login_with_wrong_password(test_client):
    """Given: 用户已注册, When: 输入错误密码, Then: 登录失败"""
    # Given: 用户已注册
    register_user(email="test@example.com", password="correct_password")

    # When: 输入错误密码
    response = test_client.post("/api/login", json={
        "email": "test@example.com",
        "password": "wrong_password"
    })

    # Then: 登录失败
    assert response.status_code == 401
    assert response.json()["error"] == "Invalid credentials"

# 测试覆盖的优先级

# 高优先级（必须测试）
1. 认证和授权逻辑
2. 支付和交易逻辑
3. 数据敏感操作（删除、修改）
4. 核心业务流程

# 中优先级（应该测试）
5. API endpoints
6. 数据转换逻辑
7. 错误处理

# 低优先级（可测试可不测试）
8. 工具函数（已经有单测）
9. 简单的 getter/setter
10. 配置文件

# 好的代码风格：PEP8 + 项目规范

class UserService:
    """用户服务"""

    def __init__(self, db: Database, cache: Cache):
        self._db = db
        self._cache = cache

    def get_user(self, user_id: str) -> User | None:
        """获取用户"""
        # 先查缓存
        cache_key = f"user:{user_id}"
        cached = self._cache.get(cache_key)
        if cached:
            return User.from_dict(cached)

        # 缓存未命中，查数据库
        user = self._db.query(User).filter(User.id == user_id).first()
        if user:
            # 写入缓存
            self._cache.set(cache_key, user.to_dict(), ttl=3600)
        return user

# 坏的代码风格：不一致
class userService:
    def __init__(self,db,cache):
        self.db=db
        self.cache=cache
    def getUser(self,id):
        user = self.db.query("select * from users where id = ?", id)
        return user

# Magic Number
def calculate_shipping_cost(weight):
    if weight < 5:
        return 10
    elif weight < 20:
        return 25
    elif weight < 50:
        return 50
    return 100

# 好的写法：命名常量
class ShippingTiers:
    """配送费用分层"""
    TIER_1_MAX_WEIGHT = 5      # kg
    TIER_2_MAX_WEIGHT = 20     # kg
    TIER_3_MAX_WEIGHT = 50      # kg

    TIER_1_COST = 10            # 元
    TIER_2_COST = 25            # 元
    TIER_3_COST = 50            # 元
    TIER_4_COST = 100           # 元（超过 TIER_3）

def calculate_shipping_cost(weight: float) -> float:
    """计算配送费用"""
    if weight <= ShippingTiers.TIER_1_MAX_WEIGHT:
        return ShippingTiers.TIER_1_COST
    elif weight <= ShippingTiers.TIER_2_MAX_WEIGHT:
        return ShippingTiers.TIER_2_COST
    elif weight <= ShippingTiers.TIER_3_MAX_WEIGHT:
        return ShippingTiers.TIER_3_COST
    return ShippingTiers.TIER_4_COST

# 清晰的模块边界

# auth/ 模块：只负责认证
auth/
├── login.py      # 登录
├── logout.py    # 登出
├── refresh.py   # Token 刷新
└── exceptions.py  # 认证相关的异常

# auth 模块不负责：
# - 数据库操作（由 data/ 模块负责）
# - 邮件发送（由 notification/ 模块负责）
# - 用户资料（由 user/ 模块负责）

# 如果 AI agent 要修改登录逻辑，
# 它知道只需要看 auth/ 模块，不需要看其他模块

# AGENTS.md - AI Agent 使用指南

## 项目概述
这是一个订单管理系统，负责处理电商平台的订单全流程。

## 技术栈
- Backend: Python 3.11 + FastAPI
- Database: PostgreSQL + Redis
- Queue: Celery + RabbitMQ
- Deploy: Docker + K8s

## 代码组织
- `src/api/` - FastAPI 路由和 schemas
- `src/services/` - 业务逻辑
- `src/models/` - SQLAlchemy 模型
- `src/tasks/` - Celery 异步任务

## 常用命令
```bash
# 启动服务
make run

# 运行测试
make test

# 数据库迁移
make migrate

# 代码检查
make lint

这个文件让 AI agent 理解项目的基本信息，不需要自己去探索。

### 2. Makefile

```makefile
# Makefile - 常用命令

.PHONY: help run test lint migrate clean

help:
    @echo "Available commands:"
    @echo "  make run      - Start the API server"
    @echo "  make test     - Run all tests"
    @echo "  make test cov - Run tests with coverage"
    @echo "  make lint     - Run linters"
    @echo "  make migrate  - Run database migrations"
    @echo "  make clean    - Clean temporary files"

test:
    pytest tests/ -v --tb=short

test cov:
    pytest tests/ -v --cov=src --cov-report=html

run:
    uvicorn src.api.main:app --reload --port 8000

lint:
    ruff check src/ tests/
    mypy src/

migrate:
    alembic upgrade head

# conftest.py - pytest 配置

import pytest
from app.test_utils import create_test_db, clean_test_db

@pytest.fixture(scope="session")
def test_db():
    """Session 级别的测试数据库"""
    db = create_test_db()
    yield db
    clean_test_db(db)

@pytest.fixture
def test_client(test_db):
    """API 测试客户端"""
    from app.test_utils import TestClient
    return TestClient(test_db)

@pytest.fixture
def auth_token(test_client):
    """认证 token"""
    return test_client.login("admin@test.com", "admin123")