软件工程的范式转移：基于 Claude Code 与智能体协作的高效编程实践

# 项目概览
电商平台后端服务，基于 FastAPI + PostgreSQL，遵循领域驱动设计（DDD）

## 技术栈
- 语言：Python 3.11+
- 依赖管理：Poetry
- 数据库迁移：Alembic
- 测试：pytest + factory_boy
- 文档：MkDocs + mkdocstrings（自动从 docstrings 生成 API 参考）

## 代码规范
- 类型注解：所有函数必须包含完整类型提示（含返回值）
- 异常处理：业务异常继承自 `DomainError` 基类
- 日志：使用 structlog，禁止使用 print()
- 测试：新功能必须附带单元测试（覆盖率 ≥80%）
- 文档：公共 API 必须包含 Google 风格 docstrings，变更后同步更新用户指南

## 关键命令
- 启动开发服务器：`poetry run uvicorn app.main:app --reload`
- 运行测试：`poetry run pytest tests/ -xvs`
- 生成数据库迁移：`poetry run alembic revision --autogenerate -m "描述"`
- 构建文档站点：`poetry run mkdocs build`
- 本地预览文档：`poetry run mkdocs serve`

# scripts/gen_ref_pages.py
"""自动生成 MkDocs 参考文档页面"""
from pathlib import Path
import mkdocs_gen_files

nav = mkdocs_gen_files.Nav()

# 递归遍历源代码
for path in sorted(Path("src").rglob("*.py")):
    # 跳过 __init__.py 和测试文件
    if path.name.startswith("__") or "test" in path.parts:
        continue
    
    module_path = path.relative_to("src").with_suffix("")
    doc_path = path.relative_to("src").with_suffix(".md")
    full_doc_path = Path("reference") / doc_path
    
    # 构建导航层级
    parts = list(module_path.parts)
    nav[parts] = full_doc_path.as_posix()
    
    # 为每个模块创建引用页面
    with mkdocs_gen_files.open(full_doc_path, "w") as fd:
        identifier = ".".join(module_path.parts)
        fd.write(f"# `{identifier}`\n\n")
        fd.write(f"::: {identifier}\n")
        fd.write("    options:\n")
        fd.write("      show_root_heading: false\n")
        fd.write("      show_source: true\n")

# 生成 SUMMARY.md 导航
with mkdocs_gen_files.open("reference/SUMMARY.md", "w") as nav_file:
    nav_file.writelines(nav.build_literate_nav())

plugins:
  - search
  - gen-files:
      scripts:
        - scripts/gen_ref_pages.py
  - literate-nav:
      nav_file: SUMMARY.md
  - mkdocstrings:
      handlers:
        python:
          options:
            docstring_style: google
            show_signature: true
            show_source: true
            merge_init_into_class: true

nav:
  - 概览: index.md
  - 用户指南: guides/
  - API 参考: reference/
  - 架构设计: architecture/

// ~/.claude/settings.json
{
  "hooks": {
    "postToolUse": [
      {
        "command": "bash .github/scripts/check-doc-impact.sh {file}",
        "onTool": "edit"
      }
    ]
  }
}

#!/bin/bash
# .github/scripts/check-doc-impact.sh
FILE=$1

# 检测是否修改了公共 API
if git diff HEAD -- "$FILE" | grep -q "^+.*def \|^-.*def \|^\+.*class \|^-.*class "; then
  echo "⚠️  检测到公共 API 变更，请同步更新文档："
  echo "   1. 检查 docstrings 是否完整"
  echo "   2. 运行: poetry run python scripts/gen_ref_pages.py"
  echo "   3. 如需更新用户指南，运行: claude code '根据新功能更新 guides/ 目录下的相关文档'"
fi

claude code "根据新添加的 PaymentService.refund() 方法，更新 guides/payments.md 中的退款流程说明"

# .github/workflows/docs.yml
name: Documentation Quality Gate

on:
  pull_request:
    paths:
      - 'src/**'
      - 'docs/**'
      - 'mkdocs.yml'

jobs:
  validate-docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: "3.11"
      
      - name: Install dependencies
        run: |
          pip install poetry
          poetry install --with docs
      
      - name: Build documentation (strict mode)
        run: poetry run mkdocs build --strict
        # --strict 会在发现 broken links 或 warnings 时失败
      
      - name: Check for stale docstrings
        run: |
          # 检测有实现但无 docstrings 的公共函数
          poetry run pylint --load-plugins pylint.extensions.docparams \
            --disable=all --enable=missing-param-doc,missing-return-doc \
            src/ || true

## 认证流程

```mermaid
sequenceDiagram
    participant U as User
    participant F as Frontend
    participant A as AuthService
    participant T as TokenService
    participant DB as PostgreSQL

    U->>F: POST /login (email, password)
    F->>A: validate_credentials(email, password)
    A->>DB: SELECT password_hash FROM users WHERE email=?
    DB-->>A: password_hash
    A->>A: bcrypt.verify(password, password_hash)
    alt valid
        A->>T: generate_jwt(user_id, roles)
        T-->>A: access_token, refresh_token
        A-->>F: {access_token, refresh_token}
        F-->>U: 200 OK
    else invalid
        A-->>F: 401 Unauthorized
        F-->>U: 错误提示
    end

开发者只需提示：
```bash
claude code "为新实现的 OAuth2 授权码流程生成 Mermaid 序列图，放入 docs/guides/auth.md"

~/.claude/skills/
├── update-docs/       # 文档更新专用技能
│   ├── SKILL.md
│   ├── templates/
│   │   ├── guide-template.md
│   │   └── api-changelog.md
│   └── examples/
│       └── payment-refund-doc.md
└── explain-code/
    └── SKILL.md

---
name: update-docs
description: "根据代码变更同步更新 MkDocs 文档，包括 API 参考与用户指南"
disable-model-invocation: false
---
# 适用场景
- 新增/修改公共 API 后更新参考文档
- 功能迭代后更新用户指南
- 重构后更新架构图

# 工作流程
1. 分析变更文件的 diff，识别影响范围
2. 检查相关模块的 docstrings 完整性
3. 更新或创建对应的 MkDocs Markdown 页面
4. 如涉及流程变更，生成 Mermaid 序列图/流程图
5. 在提交前运行 `mkdocs build --strict` 验证

# 禁止行为
- 不得删除现有文档内容（除非确认已废弃）
- 不得修改未受影响的文档章节
- 所有图表必须基于实际代码逻辑生成

# 预览文档更新计划（无副作用）
claude code --permission-mode plan "根据新 PaymentService.refund() 方法更新用户指南"

# 执行文档更新（需人工批准每步操作）
claude code "更新 guides/payments.md 中的退款流程说明，包含 Mermaid 序列图"

# 项目规范（Copilot 专用）

## 架构约束
- 所有 API 路由必须通过 `@auth_required` 装饰器
- 数据库查询必须使用 SQLAlchemy ORM，禁止原生 SQL

## 文档要求
- 公共函数必须包含 Google 风格 docstrings
- 参数描述需包含类型与业务含义（如 "user_id: int - 已认证用户的唯一标识"）

# 步骤 1：实现新功能（支付退款）
claude code "在 PaymentService 中实现 refund(transaction_id, reason) 方法，包含完整类型注解与 Google 风格 docstrings"

# 步骤 2：运行测试验证功能
poetry run pytest tests/services/test_payment.py -xvs

# 步骤 3：检测文档影响（Hooks 自动触发）
# 输出: "⚠️ 检测到公共 API 变更，请同步更新文档"

# 步骤 4：预览文档更新计划
claude code --permission-mode plan "根据新 refund() 方法更新 guides/payments.md 中的退款流程"

# 步骤 5：执行文档更新（人工批准每步）
claude code "更新 guides/payments.md：1) 添加 refund() 使用示例 2) 生成退款流程 Mermaid 序列图 3) 补充错误处理说明"

# 步骤 6：验证文档构建
poetry run mkdocs build --strict

# 步骤 7：提交变更（标记 AI 参与）
git add src/services/payment.py docs/guides/payments.md
git commit -m "[AI-assisted] 实现 PaymentService.refund() 并同步更新用户指南"