# Rebuild Reference Product

> Orchestrate a long-running, evidence-based clean-room reconstruction of an authorized reference software product. Use when Codex must inspect a reference website or application, handle user-completed QR-code or one-time-code login, inventory capabilities, maintain durable product facts, coordinate bounded subagents, design prototypes and architecture, implement vertical slices, compare behavior, debug failures, and continue until the declared scope is independently verified.

- Skill: `lichenxigk2002/rebuild-reference-product` (Agent Skill, multi-file: 8 files)
- Install (CLI): `npx skillmds@latest add lichenxigk2002/rebuild-reference-product`
- Raw SKILL.md: https://api.skillmd.com/api/skills/lichenxigk2002/rebuild-reference-product/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: lichenxigk2002 (https://skillmd.com/u/lichenxigk2002)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/lichenxigk2002/rebuild-reference-product

---


# 重建参考产品

把参考产品转换为可验证、可维护、独立实现的正式产品。复现用户可见能力、业务语义和交互结果，不复制对方源码、私有实现、商标文案或受版权保护的素材。

## 建立执行合同

1. 完整读取仓库级和修改目录就近的 `AGENTS.md`、工程宪法、架构、正式方案、接口和决策记录。
2. 使用 `git status --short` 建立基线并保留用户修改。目录不是 Git 工作树时，明确报告无法安全执行破坏性重写。
3. 确认参考产品准确地址、平台、版本、账号权限、可观察范围和用户授权方式。
4. 提取业务目标、用户可见结果、验收标准、非目标和受保护范围。
5. 遵守仓库的 L0/L1/L2 分级；新模块、鉴权、跨系统合同、migration、异步任务和数据一致性按 L2 先更新正式方案。
6. 把无法验证的事实标记为 `unknown`，禁止凭印象补齐。

## 处理扫码和验证码登录

需要认证时读取 [reference-observation.md](references/reference-observation.md)，并执行人工接管：

1. 打开参考产品的正式登录入口。
2. 告知用户当前需要扫码或输入一次性验证码。
3. 等待用户直接在浏览器中完成认证。
4. 只验证登录后的页面是否可访问。
5. 不索取、读取、记录或持久化验证码、Cookie、Authorization、完整令牌或会话导出。
6. 会话失效时明确暂停观察并再次请求人工接管，不伪装为仍有权限。

## 建立持久事实源

不要依赖聊天记录保存长期进度。按仓库文档治理维护唯一正式事实源，至少覆盖：

- 目标范围和能力台账；
- 产品、页面和交互设计；
- 架构、数据、接口与正式决策；
- 实施阶段、验证证据、剩余差异和风险。

能力台账使用 [capability-ledger.md](references/capability-ledger.md) 的格式。完成阶段验收前运行：

```bash
python3 .codex/skills/rebuild-reference-product/scripts/validate_capability_ledger.py <能力台账.md>
```

准备宣告 P0/P1 完成时增加 `--require-complete`。

## 按阶段推进

读取 [delivery-gates.md](references/delivery-gates.md)，按以下门禁连续推进：

1. **目标与权限**：确认产品身份、合法观察范围和版本基线。
2. **产品发现**：记录导航、对象、用户旅程、权限、状态、错误、快捷键、导入导出和恢复行为。
3. **产品与架构设计**：把观察结果转换为独立业务语义，更新正式方案、决策、数据和接口。
4. **真实纵向切片**：先完成一个 `UI -> Use Case -> 持久化/Provider -> 重新加载 -> 错误展示` 闭环。
5. **能力切片循环**：逐项观察、验收、设计、实现、测试、对比和更新台账。
6. **整体验收**：验证完整用户旅程、异常路径、性能、权限、并发、资源生命周期和可运维性。

每个能力切片必须：

1. 记录参考行为和证据等级；
2. 定义用户可见验收标准；
3. 实现最小完整纵向能力；
4. 覆盖主要成功路径和最有意义的错误路径；
5. 运行受影响范围的测试、类型检查、构建和质量门禁；
6. 与参考产品重新对比；
7. 更新正式事实源，不在聊天中维护孤立待办。

禁止占位成功、假数据冒充真实能力、静默 fallback、降低断言或把失败标记为完成。

## 组织团队

需要并行调研、实现或独立审查时读取 [team-protocol.md](references/team-protocol.md)。

保持主代理对范围、集成、最终 diff、验证和交付负责。只委派边界清晰的任务，例如独立旅程调研、页面状态分析、架构审查、互不重叠的实现切片和质量审查。禁止多个代理同时编辑相同文件或紧耦合调用链。

普通工程判断自主推进。只在以下情况暂停：

- 缺少会改变业务语义的决定；
- 需要扫码、验证码或新的授权；
- 需要破坏性操作或生产权限；
- 参考事实不可访问且没有合法替代证据；
- 范围需要显著扩大。

## 处理失败和重写

需要推倒重来时读取 [rewrite-policy.md](references/rewrite-policy.md)。不得因为局部失败自动删除代码。

先证明基础设计不匹配，再比较修复与重写的成本、风险、兼容和迁移影响；保留合同、测试和已验证行为；建立可恢复基线；取得用户明确确认后才能删除代码、数据或 migration。

## 定义完成

只有同时满足以下条件才宣告完整：

- 所有范围内 P0/P1 能力均为 `verified` 且证据等级为 E4；
- 不存在未知的关键能力；
- 关键用户旅程通过自动化测试和人工对比；
- 权限、持久化、恢复、并发、幂等、超时、取消和错误展示按适用范围验证；
- 类型检查、测试、构建和仓库质量门禁通过；
- 正式文档与实际行为一致；
- 不存在占位实现、伪成功、静默降级或未登记差异；
- 剩余差异已经由用户明确接受。

页面看起来相似不等于产品完成。像素级视觉一致性如果属于目标，必须作为独立验收轴记录。

## 报告结果

按仓库要求报告业务结果、已验收能力、剩余差异、关键取舍、修改范围、测试与构建结果、净代码增量、新文件、依赖、migration、风险、跳过项和规则偏差。