Skip to content

reference-analysis.md

Latest commit

 

History

History
184 lines (124 loc) · 8.33 KB

reference-analysis.md

File metadata and controls

184 lines (124 loc) · 8.33 KB

参考项目深度分析 — dev-lifecycle skill 升级调研

2026-03-28 | 基于 v2 设计方案引用的 13 个参考项目原始内容分析 目的：沉淀调研成果，避免后续重做时从头再来

一、项目级参考（6 个开源项目）

1. CCPM (automazeio/ccpm) — Script-First 项目管理

核心架构：PRD → Epic → Tasks 三层结构，每层有必填 frontmatter schema。

关键最佳实践：

实践 具体做法 对 dev-lifecycle 的启发
Script-First 14 个 bash 脚本处理所有状态查询，零 LLM 开销 v2 已采纳（status.sh/validate.sh 等）
文件领域分配 conflicts_with 互斥列表 + parallel 布尔值双重防护 v2 只有 file_scope，缺少 conflicts_with
任务上限 每个 Epic ≤10 个 task，超出先做依赖分析再批处理（5个/批） v2 无明确上限
Preflight 检查 每个 phase 开始前验证目录存在性/命名规范/文件冲突 v2 缺少显式 preflight gate
冲突协议 agent 遇冲突必须 pause+report，禁止自行解决 v2 已有（worktree 合并冲突直接报告）
PRD 质量门 禁止 placeholder 文字、metrics 必须可量化 v2 spec.md 模板用 HTML 注释，但无硬性质量检查
双维度估算 XS~XL + 小时数 v2 只有 effort: small/medium/large

2. claude-code-skills — 防投机门控体系

核心架构：levnikolaevich/claude-code-skills（128 个技能，7 个插件）。核心思路是把 prompt 规则转化为结构约束。

关键最佳实践：

实践 具体做法 对 dev-lifecycle 的启发
Research-to-Action Gate "What specific defect does this fix?" 强制前置问。调研和执行时序隔离：调研成果固化为 ADRs/guides，执行时消费而非重新调研 v2 Research Gate 是 inline 的，每次执行都重新调研
MANDATORY READ 语法 被动引用（"See X"）被 agent 忽略；强制读取用 **MANDATORY READ:** Load {file} v2 用"进入阶段时 Read references/"，可能被忽略
Quality Checklist 四级门控：Story 验证(ln-310) → Task 审查(ln-402) → 质量协调(ln-510) → 最终裁决(ln-500) v2 质量门较扁平，缺少分级
Multi-model debate 过滤 外部 agent 审查后标 AGREE/DISAGREE/UNCERTAIN，最多 2 轮辩论，≥90% 置信度 + >2% 影响才浮出 v2 圆桌无过滤机制
Token 效率模式 四大模式：懒加载、层级委托、并行 auditor、hex-line MCP 精准编辑 v2 有预算表但缺具体节省手段

3. claude-code-workflows (shinpr) — 复杂度路由 + 质量门

核心架构：requirement-analyzer → technical-designer/prd-creator → task-executor → quality-fixer 流水线。

关键最佳实践：

实践 具体做法 对 dev-lifecycle 的启发
证据驱动路由 分析器扫描代码库列出实际文件路径后定级，非凭印象 v2 的 lite/standard/thorough 判断偏主观
blocked 前置穷尽 必须先查 Design Doc → PRD → 相似代码 → 测试注释，穷尽后才能 block v2 无 blocked 前置条件
升级灰色地带 明确列举边界案例（如"添加参数 vs 接口变更"） v2 升级触发器无边界案例
设计回归检测 code-reviewer 对比实现与 Design Doc 偏差 v2 无设计回归检测

4. claude-code-workflows (OneRedOak) — 双循环 + Pragmatic Quality

核心架构：Inner Loop（开发时 slash commands）+ Outer Loop（PR 时 GitHub Actions）。

关键最佳实践：

实践 具体做法 对 dev-lifecycle 的启发
双循环一致性 本地 review 和 CI review 用同一个 subagent 定义 v2 无 CI 集成考虑
Net Positive 框架 不阻塞净改进的变更，即使不完美 v2 质量判定可参考

5. Twelve-Factor Agentic SDLC (tikalk) — 系统化 Agent 开发方法论

核心理念："开发者是编排者，AI 是实习生"

关键 Factors：

Factor 核心机制 v2 覆盖度
II. 上下文脚手架 Local + Team + External 三层 context 拉取 部分（Research Gate 三层搜索）
V. 双轨执行 每个 step 必须人工 tag [SYNC]/[ASYNC] 部分（execution_mode 是隐式推断）
VII. 自适应质量门 Micro-Review（SYNC）vs Macro-Review（ASYNC） ❌ 未覆盖
VIII. 风险测试 人定风险 → AI 生成针对性测试 → 人验证 ❌ 未覆盖

6. everything-claude-code (affaan-m) — Agent 运行时增强层

关键最佳实践：

实践 具体做法 对 dev-lifecycle 的启发
Strategic Compaction 在逻辑边界主动 compact，禁止实现中途 compact v2 无主动 compact 策略
Cold-start context brief 每个 plan step 嵌入独立上下文，新 agent 可无历史直接执行 v2 step 依赖历史上下文
15 分钟单元原则 每个任务 independently verifiable + single dominant risk + clear done v2 的 effort 估算可参考此粒度

二、官方文档参考（3 份 Anthropic 文档）

7. Claude Code Subagents 官方文档

v2 遗漏字段：

字段 说明
effort low/medium/high/max，控制推理深度（max 仅 Opus 4.6）
permissionMode default/acceptEdits/dontAsk/bypassPermissions/plan
disallowedTools 从继承列表中移除工具（比 tools 更灵活）

关键约束确认：

  • subagent 不能嵌套调用 subagent
  • memory: user 确实存在，自动注入 MEMORY.md 前 200 行/25KB
  • background subagent 启动前需权限预申请

8. Effective Harnesses for Long-Running Agents

关键最佳实践：

实践 具体做法 v2 覆盖度
JSON > Markdown tasks.json 抗 LLM 篡改 ✅ 已采纳
一次一个任务 防止 agent 一次性完成整个应用 ✅ 已采纳
init.sh 破损检测 每次 session 开始前跑基础 e2e 验证 部分（v2 定义为"环境初始化"）

9. Claude Code Best Practices 官方文档

关键最佳实践：

实践 具体做法 v2 覆盖度
compact 指令 CLAUDE.md 中写 "When compacting, preserve X" v2 PostCompact hook 是被动的
@path import 语法 拆分复杂 CLAUDE.md v2 SKILL.md 未利用

三、跨领域参考（2 份外部文档）

10. OpenAI: A Practical Guide to Building Agents

实践 说明
单 agent 优先 能力用尽前不拆分；判断标准是 tool 重叠度而非数量
Guardrails 分层迭代 先上线 → 用实际流量暴露漏洞 → 持续叠加

11. Google Agent Development Kit (ADK)

实践 说明
确定性骨架 + 涌现式填充 Sequential/Parallel/Loop 是确定性，内部 LLM 是涌现式
Trajectory 评估 不只评最终结果，还评每一步执行轨迹

四、跨项目共识

  1. 规则工程化 — prompt 规则随 token 增长衰减，关键约束必须用 hooks/scripts 硬保证
  2. 调研前置 — 所有项目都有"先搜后做"机制
  3. 确定性骨架 + 涌现式填充 — 固定流程保证可靠性，LLM 处理灵活判断
  4. JSON > Markdown — 状态管理用 JSON 抗篡改

五、social-auto 项目实战经验

来自 .dev-lifecycle/lessons-learned.md + memory/feedback_*.md

# 教训/反馈 参考
1 先调研再编码 — 30min调研=省2.5h试错 lessons-learned
2 了解平台架构是第一步 — 页面类型/路由/技术栈/Web vs App lessons-learned
3 选择器是 Web 自动化的核心 — 找元素优先于写代码 lessons-learned
4 不能跳过流程 — 用户触发 dev-lifecycle 时必须走流程 lessons-learned
5 经验可跨平台复用 — 方法论可迁移 lessons-learned
6 第一性原理拆解任务 — 核心动作→核心依赖→从依赖入手 feedback

此文档为 dev-lifecycle 升级调研的沉淀产出，用于补充细节参考。 升级方案见 upgrade-plan-final.md