ai-execution-platform/docs/process/development-standards.md

LJWX-Stock AI执行平台开发流程标准 v1.0

版本: v1.0 日期: 2025-10-29 状态: 正式发布 适用范围: LJWX-Stock AI执行平台项目 执行严格度: ★★★★★ (严格执行)

---

🚦 总体原则：从"过程驱动"转向"契约驱动"

Claude 的执行不应依赖它的"自由发挥"，而是严格依托四层约束体系：

层级	名称	职责	产出物
1️⃣	需求契约 (Requirement Contract)	明确输入输出目标、验收标准	用户故事 + 验收条件
2️⃣	技术契约 (Design Contract)	限定技术选型、架构风格、接口规范	API / 数据模型 / 架构图
3️⃣	执行契约 (Prompt Contract)	限定 Claude 的生成范围与结构	Prompt 模板 + Schema
4️⃣	验证契约 (Quality Gate)	自动检测 Claude 输出的合规性	Lint/Test/SAST/Schema 校验

核心原则: 只有满足这四个契约的任务，才能进入下一阶段。

---

🧭 阶段一：需求分析与设计阶段

✅ 阶段目标

将业务目标转换成 Claude 可执行的结构化输入。

🧩 强化约束

项	要求
用户故事格式	必须符合 Gherkin 语法（Given-When-Then）或 JSON Schema 格式
需求分解	每个用户故事绑定一个唯一 requirement_id
数据模型	设计必须输出 ER 图 + 数据字典
API 规范	必须定义 request, response, error_code 三段
UI 设计	必须输出低保真原型（Figma link 或 JSON schema）

🧪 验证点（Checkpoints）

• REQ-001: 所有用户故事是否覆盖了全部功能？
• DES-001: API 是否双向签名一致？（前端 / 后端）
• DES-002: ER 图与表结构字段是否一致？
• DES-003: UI 原型是否标注交互状态？
• PLAN-001: 开发优先级是否定义清晰？

🗂️ 输出物

• requirements/ - 用户故事集
• architecture/ - 系统与接口设计文档
• ui/ - 原型稿导出
• plan/ - 开发计划与优先级表

---

⚙️ 阶段二：渐进式开发阶段

✅ 阶段目标

以任务为单位执行 Claude 开发，确保每次产出符合 Prompt 契约与质量门禁。

🧩 强化约束

项	要求
Claude 执行	每个任务必须引用 PromptContract（明确模型、输出结构、禁用内容）
审阅流程	Claude 生成 → Schema 校验 → 人工审阅 → Merge
模型输入	Claude 仅能读取：需求文档、设计文档、API 规范（受限上下文）
模型输出	必须符合定义的 output_schema（JSON / Markdown structured）
Merge 条件	所有 Quality Gate（lint/test/typecheck/security）必须绿灯

🔍 验证点

• DEV-001: Claude 输出是否通过 Schema 验证？
• DEV-002: 是否违反安全规则（硬编码密钥、eval、console.log 等）？
• DEV-003: 是否完整实现验收标准？
• DEV-004: 是否自动生成单测并覆盖主要逻辑？
• DEV-005: 是否附上人工审阅意见记录？

🧱 任务粒度建议

类型	说明	交付物
FE	每个组件独立任务	.vue 文件 + TypeScript 接口
BE	每个 REST API 独立任务	Router + Service + Model
AI	每个模型训练/推理模块独立任务	Notebook + 脚本
OPS	每个环境配置独立任务	Dockerfile / helm chart
DOC	每个接口/模块说明独立任务	Markdown 文档

---

🧪 阶段三：测试与集成阶段

✅ 阶段目标

验证整个系统的正确性、完整性、安全性。

🧩 强化约束

项	要求
单元测试	覆盖率 ≥ 80%，必须有 Mock
集成测试	前后端接口打通，CI 自动执行
端到端测试	Playwright 自动执行核心流程
安全扫描	禁止高危 CVE 与 SQL 注入警告
用户验收	必须由人工 Reviewer 签字通过

🔍 验证点

• TEST-001: 所有 public 方法是否有单测？
• TEST-002: 所有接口是否返回正确状态码？
• TEST-003: 所有表单输入是否验证？
• SEC-001: 是否通过 SAST 扫描？
• UAT-001: 用户是否验收并签字？

⚙️ 自动化门禁（CI/CD）

类型	工具	约束
类型检查	mypy / tsc	必须无警告
Lint	ruff / eslint	零错误
测试	pytest / vitest	通过率 ≥ 90%
安全	trivy / bandit	无高危漏洞
构建	docker buildx	成功 + 多架构

---

🧩 阶段四：回溯与持续改进

✅ 阶段目标

持续提高 Claude 输出质量和审阅效率。

📊 增强约束

项	说明
Prompt 评分体系	每次 Claude 执行必须被人工打分（结构正确性、可读性、稳定性）
数据采集	所有执行日志、人工审阅记录、门禁结果入库
质量反馈	统计不同 Prompt 模板的通过率与平均回合数
自动改进	对通过率低的 Prompt 自动发起"自优化"任务

---

🔐 Claude 行为约束（全局）

1. 禁止跨阶段写入: Claude 仅能在自己所处阶段输出。

   • 例：设计阶段不能写代码，开发阶段不能改需求。

2. 禁止自由决策: 所有输入/输出必须绑定 Contract。

3. 强制输出结构化 JSON: 便于后端存档和比对。

4. 强制执行自检: 每个任务结束前，Claude 必须运行「自检 Prompt」，确认是否满足约束。

5. 所有执行过程可追踪: 执行日志、版本、文件哈希全部落地数据库。

---

🧩 可执行化模板（Claude 每次任务的上下文）

task_context:
  requirement_id: REQ-2025-0101
  design_id: DES-2025-0110
  work_item_id: T-BE-005
  prompt_contract_id: PC-FE-001
  phase: "development"
  constraints:
    must_follow_docs:
      - "architecture/api_spec.md"
      - "data_model/stock_tables.sql"
    must_pass_quality_gates:
      - "lint"
      - "typecheck"
      - "unit_test"
      - "sast"
    forbidden_patterns:
      - "eval"
      - "console.log"
      - "hardcoded password"
  deliverables:
    - file: "src/api/stockService.py"
    - file: "tests/test_stockService.py"
  output_format: "structured_json"
  reviewers:
    - name: "Bruno Gao"
      roles: ["Architect", "Reviewer"]

---

🧾 交付追踪标准

阶段	必交文档	验收标准	验证方式
需求分析	需求说明书.md	100% 用户故事定义	结构化 JSON 校验
设计阶段	API规范.md, ER图	设计与需求一致	Schema 比对
开发阶段	任务产物 + 测试报告	Quality Gates 全绿	CI 验证
测试阶段	测试报告 + CI日志	所有测试通过	自动门禁
验收阶段	验收签字表	审阅通过	人工签字
回溯阶段	Prompt表现分析	通过率↑	报表分析

---

🚀 Claude 项目开发「黄金闭环」

flowchart LR
  R[需求契约] --> D[设计契约]
  D --> E[执行契约]
  E --> Q[质量门禁]
  Q --> A[人工审阅]
  A --> F[反馈回流]
  F -->|改进Prompt| E
  F -->|更新需求| R

每个阶段都可通过"契约 + 校验 + 审阅"形成闭环。

---

📋 执行检查清单

项目启动前检查

• 所有需求契约已创建并评审通过
• 所有设计契约已完成并签署
• Prompt契约库已初始化
• 质量门禁规则已配置
• 审核人员权限已分配
• CI/CD流水线已配置完成

每个任务执行前检查

• 任务绑定了正确的 requirement_id 和 design_id
• 选择了合适的 Prompt契约模板
• 质量门禁规则已确认
• 审核人员已指定
• 交付物清单已明确

任务完成后检查

• 所有交付物已生成
• 通过了所有质量门禁
• Schema 验证已通过
• 单元测试已编写并通过
• 审核人员已审阅并签字
• 执行日志已完整记录

---

⚠️ 违规处理机制

轻微违规（警告）

• 未按要求格式输出
• 轻微代码规范问题
• 文档不完整

处理方式: 重新执行，记录违规次数

中度违规（失败）

• 违反安全规则
• 未通过质量门禁
• 验收标准未满足

处理方式: 任务失败，需要人工干预后重新执行

严重违规（终止）

• 硬编码敏感信息
• 跨阶段操作
• 多次轻微违规

处理方式: 立即终止执行，启动安全事故流程

---

📈 持续优化机制

周期性回顾

• 每周: Prompt效果统计和分析
• 每月: 质量门禁规则优化
• 每季度: 整体流程效率评估

自动化改进

• 基于 AI 的 Prompt 优化建议
• 质量门禁阈值自动调整
• 审核效率智能分析

---

📞 支持与反馈

• 流程问题: 联系项目架构师
• 技术问题: 联系技术负责人
• 质量问题: 联系质量保证团队
• 紧急事故: 启动应急响应流程

---

更新记录:

版本	日期	更新内容	更新人
v1.0	2025-10-29	初始版本，基于四层契约体系	Claude AI

---

本流程标准是 LJWX-Stock AI执行平台的核心执行规范，所有项目参与者必须严格遵循。流程的持续优化基于实际执行数据和反馈，确保平台效率和质量不断提升。