分析项目
/analyze-project — 根因分析工作流
分析 ~/.gemini/antigravity/brain/ 中的 AI 辅助编码会话，并生成一份报告。该报告不仅解释发生了什么，还解释为什么发生、谁/什么导致了该结果以及下次应该做出怎样的改变。
目标
针对每个会话，确定：
1. 从初始需求到最终执行的工作发生了哪些变化
2. 主要原因是否为：
- 用户/规格说明 (user/spec)
- 智能体 (agent)
- 仓库/代码库 (repo/codebase)
- 验证/测试 (validation/testing)
- 任务本身的复杂度 (legitimate task complexity)
3. 初始提示词是否充分
4. 哪些文件/子系统与反复出现的困难相关联
5. 哪些改变能最有效地改善未来的会话
使用场景
- 需要对 AI 辅助编码会话进行事后分析，尤其是出现范围漂移或重复返工时。
- 需要根因分析，以区分用户/规格问题、智能体错误、仓库摩擦或验证缺失。
- 需要有证据支撑的建议，以改进未来的提示词、仓库健康度或交付工作流。
全局规则
- 将
.resolved.N的计数视为迭代信号，而非失败证明
- 区分人为增加的范围、必要的发现范围和智能体引入的范围
- 区分智能体错误与仓库摩擦
- 每项诊断必须包含证据和置信度
- 置信度等级：
- 证据优先级：
- 如果证据不足，请如实说明
---
步骤 0.5：会话意图分类
根据目标和产出物对主要会话意图进行分类：
DELIVERY(交付)
DEBUGGING(调试)
REFACTOR(重构)
RESEARCH(研究)
EXPLORATION(探索)
AUDIT_ANALYSIS(审计分析)
记录：
session_intent(会话意图)
session_intent_confidence(意图置信度)
使用意图来衡量严重程度和返工形式。
不要用狭义交付会话的标准来衡量探索性或研究性会话。
---
步骤 1：发现会话
1. 从系统上下文中读取可用的会话摘要
2. 列出用户 Antigravity brain/ 目录中的会话文件夹
3. 构建会话索引，包含：
- conversation_id
- title
- objective
- created
- last_modified
4. 如果用户提供了关键字/路径，则过滤匹配的会话；否则分析所有会话
输出：待分析的会话索引列表。
---
步骤 2：提取会话证据
针对每个会话，读取（如果存在）：
核心产出物
task.md
implementation_plan.md
walkthrough.md
元数据
*.metadata.json
版本快照
task.md.resolved.0 ... N
implementation_plan.md.resolved.0 ... N
walkthrough.md.resolved.0 ... N
其他信号
- 其他
.md产出物
- 产出物更新之间的时间戳
- 计划/回顾中提到的文件/文件夹/子系统名称
- 验证/测试相关的语言描述
- 明确的验收标准、约束条件、非目标以及目标文件
为每个会话记录：
#### 生命周期
has_task
has_plan
has_walkthrough
is_completed
is_abandoned
d_candidate = 任务存在但无 walkthrough
#### 修订 / 变更量
task_versions
plan_versions
walkthrough_versions
extra_artifacts
#### 范围
task_items_initial
task_items_final
task_completed_pct
scope_delta_raw
scope_creep_pct_raw
#### 时间
created_at
completed_at
duration_minutes
#### 内容 / 质量
objective_text
initial_plan_summary
final_plan_summary
initial_task_excerpt
final_task_excerpt
walkthrough_summary
mentioned_files_or_subsystems
validation_requirements_present
acceptance_criteria_present
non_goals_present
scope_boundaries_present
file_targets_present
constraints_present
---
第 3 步：Prompt 充分性
对初始请求在 0–2 分范围内进行评分，维度包括：
- 清晰度 (Clarity)
- 边界感 (Boundedness)
- 可测试性 (Testability)
- 架构具体度 (Architectural specificity)
- 约束意识 (Constraint awareness)
- 依赖意识 (Dependency awareness)
创建：
prompt_sufficiency_score
prompt_sufficiency_band= High / Medium / Low
随后记录哪些缺失的 Prompt 要素可能导致了后期的摩擦。
不要默认惩罚短 Prompt；一个范围狭窄且显而易见的任务仍可能具有高充分性。
---
第 4 步：范围变更分类
将范围变更分类为：
- 人为增加的范围 (Human-added scope) —— 超出原始任务的新需求
- 必要的发现范围 (Necessary discovered scope) —— 为正确完成原始任务而必须进行的工作
- Agent 引入的范围 (Agent-introduced scope) —— 由 Agent 引入的可能不必要的工作
记录：
scope_change_type_primary
scope_change_type_secondary(可选)
scope_change_confidence
- 证据 (evidence)
记住一个简短的示例用于校准：
- 人为增加：“既然你在这，顺便把附近的代码重构一下”
- 必要发现：必须修复隐藏的依赖项，原始任务才能运行
- Agent 引入：未被要求且非必须的额外清理或重新设计
---
第 5 步：返工形态 (Rework Shape)
将每个会话归类为一种主要模式：
- 流畅执行 (Clean execution)
- 早期重新规划后稳定完成 (Early replan then stable finish)
- 渐进式范围扩张 (Progressive scope expansion)
- 反复开启/关闭的波动 (Reopen/reclose churn)
- 后期验证波动 (Late-stage verification churn)
- 中途放弃 (Abandoned mid-flight)
- 探索性 / 研究性会话 (Exploratory / research session)
记录：
rework_shape
rework_shape_confidence
- 证据 (evidence)
---
第 6 步：根因分析
对于每个非流畅执行的会话，分配：
主要根因
以下之一：SPEC_AMBIGUITY(需求模糊)
HUMAN_SCOPE_CHANGE(人为范围变更)
REPO_FRAGILITY(代码库脆弱)
AGENT_ARCHITECTURAL_ERROR(Agent 架构错误)
VERIFICATION_CHURN(验证波动)
LEGITIMATE_TASK_COMPLEXITY(合理的任务复杂度)
次要根因
若有实质性影响则可选根因指南
- SPEC_AMBIGUITY: 初始请求缺乏边界、目标、标准或约束
- HUMAN_SCOPE_CHANGE: 用户扩大了任务范围导致范围扩张
- REPO_FRAGILITY: 隐藏的耦合、脆弱的文件、不清晰的架构或环境问题导致了额外工作
- AGENT_ARCHITECTURAL_ERROR: 找错文件、假设错误、方法错误、幻觉出结构
- VERIFICATION_CHURN: 实现基本正确，但测试/验证导致了循环
- LEGITIMATE_TASK_COMPLEXITY: 考虑到难度，修订在预期之内且无法明显避免
每个根因分配必须包含：
- 证据 (evidence)
- 为什么拒绝了更强有力的替代根因
- 置信度 (confidence)
---
第 6.5 步：会话严重程度评分 (0–100)
为每个会话分配一个严重程度分数，以便优先处理。
组成部分（求和，限制在 0–100 之间）：
- 完成失败: 0–25 (
abandoned = 25)
- 重新规划 i
- 强度 (Intensity)：0–15
- 范围不稳定性 (Scope instability)：0–15
- 重构形状严重程度 (Rework shape severity)：0–15
- 提示词充分性缺失 (Prompt sufficiency deficit)：0–10 (
low = 10)
- 根因影响 (Root cause impact)：0–10 (
REPO_FRAGILITY/AGENT_ARCHITECTURAL_ERROR最高)
- 热点重复出现 (Hotspot recurrence)：0–10
分级 (Bands)：
- 0–19 低 (Low)
- 20–39 中等 (Moderate)
- 40–59 显著 (Significant)
- 60–79 高 (High)
- 80–100 关键 (Critical)
记录项：
session_severity_score(会话严重程度得分)
severity_band(严重程度分级)
severity_drivers(严重程度驱动因素) = 前 2–4 个主要贡献项
severity_confidence(严重程度置信度)
将严重程度作为优先级信号，而非最终判定。务必解释驱动因素。
结合会话意图对严重程度进行情境化分析，以免研究/探索类会话被过度扣分。
---
步骤 7：子系统 / 文件聚类
在所有对话中，按文件、文件夹或子系统对重复出现的困难点进行聚类。
针对每个聚类，计算：
- 涉及该聚类的对话数量
- 平均修订次数
- 完成率
- 放弃率
- 常见根因
- 平均严重程度
目标：识别摩擦主要是由提示词驱动、智能体驱动，还是集中在特定的代码库区域。
---
步骤 8：对比队列 (Comparative Cohorts)
对比以下组别：
- 首次尝试成功 vs 重新规划的会话
- 已完成 vs 已放弃
- 高提示词充分性 vs 低提示词充分性
- 窄范围 vs 高范围增长
- 短会话 vs 长会话
- 低摩擦子系统 vs 高摩擦子系统
针对每项对比，识别：
- 实质性的差异点
- 哪些提示词特征与更顺畅的执行相关
- 哪些代码库特征与重复性困难相关
不要简单地重复平均值，而要提取有谨慎证据支撑的模式。
---
步骤 9：非显而易见的发现 (Non-Obvious Findings)
生成 3–7 项非简单指标重复的发现。
每项发现必须包含：
- 观察结果
- 为什么重要
- 证据
- 置信度
强有力发现的示例：
- 重新规划主要集中在文件定位错误，而非验收标准模糊
- 范围增长通常发生在初步成功之后，表明是成功后的用户扩展
- 鉴权相关的困难更多是由代码库脆弱性而非智能体幻觉驱动的
---
步骤 10：报告生成
创建 session_analysis_report.md，结构如下：
📊 会话分析报告 — [项目名称]
生成时间: [timestamp]
分析对话数: [N]
日期范围: [earliest] → [latest]
执行摘要 (Executive Summary)
| 指标 | 数值 | 评级 |
|:---|:---|:---|
| 首次尝试成功率 | X% | 🟢/🟡/🔴 |
| 完成率 | X% | 🟢/🟡/🔴 |
| 平均范围增长 | X% | 🟢/🟡/🔴 |
| 重新规划率 | X% | 🟢/🟡/🔴 |
| 中位数时长 | Xm | — |
| 平均会话严重程度 | X | 🟢/🟡/🔴 |
| 高严重程度会话 | X / N | 🟢/🟡/🔴 |
阈值：
- 首次尝试：🟢 >70 / 🟡 40–70 / 🔴 <40
- 范围增长：🟢 <15 / 🟡 15–40 / 🔴 >40
- 重新规划率：🟢 <20 / 🟡 20–50 / 🔴 >50
平均严重程度指南：
- 🟢 <25
- 🟡 25–50
- 🔴 >50
注：平均严重程度是整体健康信号，与单次会话的严重程度分级不同。
随后添加一段简短的叙述性总结，说明哪些方面进展顺利，哪些方面出现了问题，以及主要问题是出在提示词质量、代码库脆弱性、工作流纪律还是验证反复上。
根因分析 (Root Cause Breakdown)
| 根因 | 数量 | 百分比 | 备注 |
|:---|:---|:---|:---|
提示词充分性分析 (Prompt Sufficiency Analysis)
- 高充分性提示词的共同特征
- 低充分性提示词中常见的缺失输入
- 哪些缺失的提示词要素与重新规划或放弃最相关
范围变更分析 (Scope Change Analysis)
区分：- 人为增加的范围
- 过程中必须发现的范围
- Agent 引入的范围
重构形态分析
总结各会话中的主要失败模式。摩擦热点
展示与重新规划、放弃、验证反复以及高严重程度最相关的文件/文件夹/子系统。首轮成功案例
列出最简洁的会话，并提取其成功原因。非显而易见的发现
列出 3-7 项有证据支撑的发现，并标注置信度。严重程度分级
列出严重程度最高的会话，并说明最佳干预措施是：- 提示词优化
- 范围约束
- 针对性的技能/工作流
- 仓库重构 / 架构清理
- 验证/测试框架改进
建议
每项建议请包含：- 观察到的模式
- 可能原因
- 证据
- 拟采取的变更
- 预期收益
- 置信度
逐次对话分析
| # | 标题 | 意图 | 时长 | 范围变化 | 计划修订 | 任务修订 | 根本原因 | 重构形态 | 严重程度 | 是否完成 |
|:---|:---|:---|:---|:---|:---|:---|:---|:---|:---|:---|
---
步骤 11：可选的分析后改进
如果适用，还需：
- 更新任何本地项目健康状况或记忆产出物（如果存在），记录重复出现的失败模式和脆弱的子系统
- 根据高充分性/首轮成功会话生成
prompt_improvement_tips.md
- 当同一子系统或任务序列反复导致困难时，建议缺失的技能或工作流
仅在模式重复出现时才建议工作流/技能。
---
最终输出标准
工作流必须产出：
1. 指标摘要
2. 根本原因诊断
3. 提示词充分性评估
4. 子系统/摩擦映射图
5. 严重程度分级与优先级排序
6. 有证据支撑的建议
7. 非显而易见的发现
倾向于明确表达不确定性，而非伪造精确度。
局限性
- 仅在任务明确符合上述范围时使用此技能。
- 不要将输出视为环境特定验证、测试或专家评审的替代方案。
- 如果缺少必要的输入、权限、安全边界或成功标准，请停止并请求澄清。
