Formalized, Reviewed, Triaged — 从业者的报告，第二部分

Source: Dev.to

Hook

运行 paragraf 项目的工作池模式定义了三种工作类型：spec、package 和 issue‑bucket。其中只有两种有明确的流程。

第一篇文章介绍了一种产生可用库的方法论。随后的一周内出现了两项并行的改进：

1. 一个冲刺交付了两个新的与颜色相关的包。
2. 将该方法论正式化，以处理 spec 和 package 工作。

在 article‑1 中，方法论是一种实践；一周后它成为了文档化的流程。

方法论文档

docs/
├── methodology.md              # phases, gates, ask‑human triggers
├── methodology-reference.md    # archive procedures, anti‑patterns
├── outer-context.md            # project‑level consistency checker
├── work-pool.md                # work registry + state machine
├── glossary.md                 # defined terms, hierarchy summary
├── dependency.md               # project‑level dependency map
├── io-schemas.md               # project‑level I/O navigation
├── roadmap.md                  # strategy and milestones
├── AI-PRIMER.md                # minimal session bootstrap
│
├── inner-context/[package]/
│   ├── inner-context.md        # role, constraints, package rules
│   ├── io-schema.md            # public types, exported functions
│   ├── dependency.md           # package imports
│   └── decisions.md            # active draft decisions only
│
├── plan/
│   └── workId-package-spec-plan-[YYMMDD-HHMM].md
│
└── archive/
    ├── plan/done/
    ├── plan/cancelled/
    └── decision/[package]-decisions-archive.md

• 每个文档都有唯一的角色。
• methodology.md 是指令集（四个阶段）。
• outer-context.md 提供项目层面的统一性检查。
• work-pool.md 是带有显式状态机的工作登记册。
• decisions.md 保存进行中的决策，决策一旦确定就会转化为一行约束。

推动这一观察的动机很简单：在 article‑1 中，方法论经受了快速迭代周期的考验，而当两个彩色包在其下发布时，新流程证明了其价值。

实践中的形式化

在冲刺期间，出现了设计逆转：最初直接将 OutputIntent 导入 render‑pdf 的选择，被记录在 decisions.md 中的新草案决定所取代。决策生命周期在没有仪式感的情况下处理了此事，展示了形式化流程能够优雅地容纳逆转。

• 测试通过。
• 端到端运行全部成功。

Article‑1 描述了一个审计时刻（excuse-me-kemal-I-forked-up.md），当时单元测试失败。随后进行的评审正是基于那次经验展开的。

审查过程与发现

四类发现

五步审查工作流

1. Claude Opus 对整个代码库进行审查 – 代码库已上传至审查环境。

2. VS Code Copilot 交叉检查并补充 – Copilot 添加了发现，纠正了优先级，并缩小了范围。

3. VS Code Copilot 批量修复 – 将项目分组并修复。

4. 在差异上进行 GitHub Copilot 审查，然后进行 Copilot 修复 – 运行三次：

   gh pr view --json reviews,comments \
     --jq '.reviews[].body, .comments[].body' \
     > docs/findings-I.md

   这生成了 findings-I.md、findings-II.md、findings-III.md，评论数分别为 7、11、6。每个文件都已审查并修复问题。

5. Opus 的最终结构性检查 – 将更新后的代码库返回进行结构和架构审查。

总计约 105 条发现，来源于两方：Opus 提供 81 条，其余来自 Copilot。书面的方法论可以与其产出进行对照检查。

Issue‑Bucket 差距

工作池模式列出了三种工作类型：spec、package 和 issue‑bucket。虽然 spec 和 package 工作有明确的流程，issue‑bucket 工作却没有。该类型作为一等条目存在，但缺乏正式的生命周期。

具体示例：在审查过程中，对 @paragraf/render-pdf 和 @paragraf/compile 产生了一个发现。问题出在操作员的思维中，而不是设备本身。这直接关联到排版与字体设计的区别，并呼应了上表中讨论的“虚假保证测试”。

这一差距并非形式化的失败；它反映了任何过程的真实局限。原始的 81 项中仍有 22 项未结，但它们并非残留问题——它们凸显了建立明确的 issue‑bucket 循环的必要性。

结论

一周内的两项改进——在正式化方法论下发布的两个新包——展示了该过程可以从实践扩展到有文档的程序。这个经验不仅适用于 paragraf：任何能够长期开发的 LLM‑辅助系统都受益于清晰、书面的方法论。

本系列的下一篇文章将在 issue‑bucket loop 关闭后进行讨论。paragraf 仓库、在线演示以及文章系列均为开源：

github.com/kadetr/paragraf