AI Coding SOP 严格开发交付标准 v2

五、设计方案文档标准

完整设计包包含：03-system-design + 04-database-design + 05-api-integration-design + 06-frontend-design + 07-security-permission-design + 08-test-case-design + 15-deployment-rollback-plan

03-system-design 核心章节

Context / Goals / Non-Goals / Current Architecture / Target Architecture / Module Boundaries / Data Flow / State Flow / Core Workflows / Error Handling / Dependencies / Configuration / Observability / Performance / Rollback Strategy / Risks / Open Questions

04-database-design 核心章节

Data Requirements / Entity Relationship / Tables / Fields / Constraints / Indexes / Query Patterns / Migration Plan / Backfill Plan / Seed Data / Data Permissions / Data Consistency / Rollback Plan / Risks

05-api-integration-design 核心章节

Integration Scope / API Contract / Request/Response Schema / Error Codes / Authentication / Authorization / Idempotency / Retry Policy / Timeout Policy / Rate Limit / Versioning / Contract Tests / Mock Strategy / Risks

06-frontend-design 核心章节

Page Goals / Target Users / Information Architecture / User Flow / Layout / Component Inventory / State Inventory / Responsive Behavior / Design Tokens / Accessibility / Empty-Loading-Error States / Visual QA Criteria / Risks

视觉禁区（必须明确禁止）

• 随机紫蓝渐变
• 装饰性发光球
• 玻璃拟态
• 卡片套卡片
• 工具型页面使用过大 hero
• 所有信息都做成等权重方块

六、Codex-only 开发 SOP（默认模式）

Codex-only 是默认开发模式。除非用户提供设计 Agent 的前端设计产物并确认切换，否则所有开发工程都按本模式执行。

适用场景

后端开发、全栈功能、内部工具、管理后台、数据平台、MVP、常规业务功能、已有设计系统的前端项目。

标准流程

开发前门禁

• 没有裁剪决策，不开始
• 没有需求或需求摘要，不开始
• 涉及系统变化但没有系统设计，不开始
• 涉及数据库但没有数据库设计，不开始
• 涉及接口但没有接口设计，不开始
• 涉及前端但没有前端设计，不开始
• 没有开发计划，不开始
• 没有测试用例设计，不开始

前端任务特殊要求

Codex-only 中的前端设计必须包含：信息架构、页面结构、组件清单、状态清单、响应式策略、视觉禁区、截图验收标准。

完成前必须有：桌面截图 QA、移动端截图 QA、文本溢出检查、状态检查。

Codex 必须避免：把所有内容做成 card、使用无意义渐变和发光装饰、工具型页面做成营销页、只写代码不看截图。

七、Design-Agent + Codex 开发 SOP

Design-Agent + Codex 是条件模式。它只在前端设计部分引入设计 Agent，其余开发交付流程仍由 Codex 负责。

触发条件

当检测到以下任一内容时，Codex 应询问用户是否切换：

• Figma 链接
• 原型图 / UI Design Spec
• Design Agent Handoff / Design Tokens / 组件规范
• 用户明确说明"这是设计 Agent 的设计方案"

角色边界

Design Agent 必需交付物

design/ui-design-spec.md + design/design-agent-handoff.md + design/prototype.md

推荐：visual-direction.md + design-tokens.md + component-spec.md + screenshots/

Codex 设计审查清单

• 设计是否和 PRD 一致
• 设计是否和系统设计冲突
• 设计是否要求不必要的新依赖
• 设计是否缺少响应式方案
• 设计是否缺少交互状态
• 设计是否缺少错误/空/加载状态
• 是否存在明显可访问性问题
• 是否能映射到项目组件

八、开发与测试标准

09-development-plan 质量标准

• 每个步骤都应可执行、可验证
• 不允许"完善前端""优化逻辑"这种模糊任务
• 涉及数据库、接口、前端、安全时，必须引用对应设计文档

11-development-log 质量标准

• 不能只写"继续开发"
• 任何偏离设计或计划的行为都必须记录
• 任何新增依赖或架构调整都必须记录

13-test-report 命令记录标准

必须记录实际命令，例如 npm run lint、npm test、npm run build。不能只写"已测试""测试通过""页面正常"。

视觉 QA 报告

前端任务必须在测试报告或单独视觉 QA 报告中记录：桌面视口、移动端视口、截图位置、视觉层级检查、响应式检查、文本溢出检查、状态检查、AI 模板感检查。

检查项：是否过多卡片、是否方块堆叠、是否视觉层级不清、是否使用无意义渐变、是否缺少 hover/focus/disabled/loading 状态、是否移动端遮挡或溢出。

九、AGENTS 自动应用规则

要让 SOP 自动应用，需要把规则写入项目 AGENTS.md 或全局 Codex 指令。

可自动化的范围

• 默认选择 Codex-only
• 检测设计 Agent 产物
• 询问用户是否切换
• 按任务等级生成文档清单
• 阻止无设计直接开发
• 阻止无测试报告直接完成

不可保证的范围

• 识别看不到的外部设计资料
• 在没有 AGENTS.md 的项目中自动生效
• 静默替用户确认模式切换

AGENTS.md 推荐配置

# AI Coding SOP

## Default SOP
All development tasks default to Codex-only SOP.

Codex must not start implementation until it has:
1. Determined task level: L0, L1, L2, L3, or L4.
2. Created or updated `00-tailoring-decision.md`.
3. Produced the required process documents for that level.
4. Produced `09-development-plan.md`.
5. Produced `08-test-case-design.md`.

## Task Levels
- L0: tiny fix or isolated change
- L1: small feature
- L2: standard feature
- L3: multi-module feature
- L4: production-critical or high-risk change

Tailoring is allowed, but every omitted document must be listed in
`00-tailoring-decision.md` with a reason and risk.

## Design-Agent Detection
If detected, Codex must ask:
"I detected design-agent frontend artifacts. Should I switch to
Design-Agent + Codex SOP for this task?"
Codex must not switch silently.

## Completion Gate
Codex must not claim completion unless:
- required process documents exist or are explicitly tailored out
- implementation matches approved design
- tests were run or skipped with a documented reason
- `13-test-report.md` exists
- frontend changes have visual QA evidence
- `17-delivery-summary.md` exists

任务启动检查

1. Is this a development task?
2. What is the task level?
3. Which documents are required?
4. Which documents can be tailored out?
5. Is frontend involved?
6. Are design Agent artifacts present?
7. Should the user confirm Design-Agent + Codex mode?
8. Is implementation allowed to start?

完成前检查

1. Did I satisfy PRD acceptance criteria?
2. Did I follow system design?
3. Did I document database/API/frontend/security changes?
4. Did I maintain development log when required?
5. Did I run tests?
6. Did I document skipped tests?
7. Did I produce delivery summary?
8. If frontend changed, did I verify desktop and mobile UI?

十、模板集合

以下是各文档的模板结构，可直接复制使用。每个文档都必须包含 YAML frontmatter。

---
title: "Tailoring Decision - TASK"
type: "tailoring"
status: "ready"
owner: "codex"
mode: "codex-only"
level: "L2"
task: "YYYY-MM-DD-task-name"
created: "YYYY-MM-DD"
updated: "YYYY-MM-DD"
related: []
---

# Tailoring Decision

## Task
## Level
## Mode
## Rationale

## Required Documents

## Tailored-Out Documents

| Document | Reason | Risk |
|---|---|---|

## User Confirmation

# PRD

## Background
## Target Users
## User Problem
## Goals
## Non-Goals
## User Flow
## Functional Scope
## Acceptance Criteria
## Constraints
## Risks
## Open Questions

# System Design

## Context
## Goals
## Non-Goals
## Current Architecture
## Target Architecture
## Module Boundaries
## Data Flow
## State Flow
## Core Workflows
## Error Handling
## Dependencies
## Configuration
## Observability
## Performance Considerations
## Rollback Strategy
## Risks
## Open Questions

# Frontend Design

## Page Goals
## Target Users
## Information Architecture
## User Flow
## Layout
## Component Inventory
## State Inventory
## Responsive Behavior
## Design Tokens
## Accessibility
## Empty Loading Error States
## Visual QA Criteria
## Risks

# Test Case Design

## Test Scope
## Acceptance Criteria Mapping
## Unit Tests
## Integration Tests
## E2E Tests
## Visual Tests
## Accessibility Tests
## Security Tests
## Performance Tests
## Regression Tests
## Manual Verification
## Out of Scope

# Development Plan

## Inputs
## Scope
## Out of Scope
## File Changes
## Implementation Steps
## Database Steps
## API Steps
## Frontend Steps
## Security Steps
## Test Steps
## Verification Commands
## Rollback Points
## Risks

# Development Log

## YYYY-MM-DD HH:mm
### Action
### Files Changed
### Decisions
### Problems
### Resolution
### Deviations
### Next

# Test Report

## Environment
## Commands
## Results
## Failed Cases
## Fixes
## Not Run
## Residual Risks
## Conclusion

# Delivery Summary

## Task
## Mode and Level
## Completed Work
## Files Changed
## Documents
## Verification
## Deployment Status
## Known Limitations
## Risks
## Follow-Up

一句话总结