<img src="../banner.png" width="100%" alt="pipeline-optimizer banner">

中文 — pipeline-optimizer 官方中文版本。

Pipeline Optimizer / Project-Folder Optimizer (中文)

无不兼容问题的6步骤改造流程 — 适用于两个层级：

触发器名称	作用域	示例
Pipeline optimizer	整个流水线、技术栈、文档结构	您的主题流水线，例如 software/、research/、games/、智能体系统
Project-folder optimizer	流水线内的独立项目文件夹	软件工具、论文项目、游戏项目

这里的**流水线（pipeline）**是指面向主题的顶层结构，多个项目在其中基于共享规范共同存在（例如包含发布规则的软件流水线、包含出版流程的研究流水线）。

两者均采用相同的6步骤工作流 — 唯一的区别在于作用域（全流水线范围 vs. 单个项目），并相应决定步骤 A 中既有资产调查的深度。

何时适用本 Skill

当要求您改进、重构或扩展现有结构时（而非用于全新的空地建设/greenfield），即适用本 Skill。具体触发词：

流水线层级（作用域：整个流水线）：

• “改进流水线 X”
• “优化技术栈”
• “改造软件流水线”
• “研究流水线中的文档整合”
• 对主题流水线、中央 _tools/ 或系统组件进行实质性干预

项目文件夹层级（作用域：单个项目文件夹）：

• “清理 / 优化项目文件夹 X”
• “改进 Y 中的文件夹结构”
• “重构单个工具”
• “统一论文项目设置”
• “使游戏项目文件夹符合流水线标准”

横向/跨切面：

• “重构 X / 将其集成到现有 Y”
• “重构”、“整合”
• “统一规范”
• “集成到现有系统”

既有建筑/资产比喻

改造房屋首先需要知道它是用什么建造的（石头、木头、塑料）、它的用途是什么（山间小屋、软件工坊）以及它已经在哪里发挥作用。这一原则同样适用于流水线。

---

实施步骤 — 6个步骤（切勿跳过，切勿重排顺序）

步骤 A — 调查既有资产

问题： 房屋是由什么构成的？

流水线作用域（所有根文档 + 工具 + 模板）：

• 完整阅读所有根文档（不仅是代码片段/插入点）
• 检查模板文件夹（_templates/、_TEMPLATES/）和工具文件夹（_tools/）
• 规范文件：例如 GITHUB-POLICY.md、RELEASE-MANAGEMENT.md、QUALITY_RULES.md、NAMING-SYSTEM.md、出版流程等…
• 状态快照：例如 PROJECT_STATUS.md、状态概览、releases.json、注册表文件
• 检查清单：例如发布检查清单、构建/PDF检查清单
• 工作流文件：AGENTS.md、GUIDE.md、SKILL.md
• 经验教训文件：LESSONS_LEARNED.md、MEMORY.md、循环状态文件

项目文件夹作用域（单个项目实质内容 + 相关的流水线规范）：

• 阅读项目文件夹中的所有 Markdown 和控制文件（README、CHANGELOG、TASKS/TODO、DONE、CONCEPT、行动计划、证明笔记等）
• 调查代码结构： src/、tests/、构建配置（pyproject.toml、requirements.txt、项目清单、工具链文件等）
• 考量父流水线的规范（例如对于软件项目：GitHub 策略、命名系统、发布管理、模板）
• 扫描项目中现有的工具/脚本（_tools/、_scripts/、build_*.bat、START 脚本）
• 配置文件： .gitignore、LICENSE、NOTICE、SECURITY.md、CODE_OF_CONDUCT.md

反模式： 使用 grep -l "<keyword>" 查找插入点并在不了解文件上下文的情况下直接插入。

输出： 在所选作用域内包含所有相关规范、工具和模板的清单记录。

步骤 B — 明确存在目的

问题： 房屋为何而存在？

用 1-2 句话明确阐述其存在目的。

流水线示例：

流水线	目的
软件流水线	开发、测试并发布桌面应用 + 浏览器工具到应用商店/GitHub
研究流水线	撰写学术论文、同行评审并发布至代码库/预印本服务器
游戏流水线	开发游戏并发布到目标平台
智能体系统	用于多智能体协同编排的 LLM 系统

项目文件夹示例：

项目文件夹	目的
software/PlannerApp	计划管理桌面应用，商业项目，私有仓库
research/CosmologyModel	模型论文系列 + 数值计算
games/SortingChaos	分类游戏，Alpha 阶段，关卡推进

存在目的指导每一次干预 — 不服务于该目的的措施将被直接舍弃。

步骤 C — 勾勒理想蓝图

问题： 为此目的打造的完美房屋应该是什么样子？

• 从您自身的视角进行勾勒（简短，最多 10 点）
• 引入最佳实践对比（例如 SaaS 的 Vercel 栈，研究领域的 scientific-python 栈）
• 切勿陷入细节优化 — 高层级的概要草图即可

输出： 5-10 点“每个流水线的理想状态”

步骤 D — 差距分析与规划

每个流水线需回答四个问题：

1. 房屋已经具备什么？ — 即使解决方式与理想状态不同，但功能上等效。 示例： 理想状态要求“使用 pip-licenses 处理第三方许可证”。现实情况：通过自定义生成器脚本包裹它 → 功能等效，无需干预。

2. 什么妨碍了功能？ — 当前导致中断或产生额外负担的既有结构。

3. 什么是不具备功能的？ — 死代码、过时的规范、未使用的工具。

4. 什么能显著改进功能？ — 带来预期收益的具体干预措施。

→ 由此制定具体计划：

• 什么需要新建？
• 什么需要扩展？
• 什么需要拆除？
• 什么保持不变（明确指出这一点非常重要！）

输出： 包含列 干预事项 / 现有状况 / 改进措施 / 依据理由 的计划表

步骤 E — 基于实证开展工作

切勿仅自顶向下规划 — 收集实际痛点：

• 已知 Bug：Issue 跟踪器、TASKS/TODO/DONE 文件
• 错误历史：经验教训文件、Bug 修复日志、检查注册表
• 自动化中断：“有什么工作是我总是必须手动完成的？”
• 用户访谈：针对性询问 — 痛点、愿望、变通方案
• 自我测试：完整走一遍流水线（创建新项目、运行构建、模拟发布）— 在何处发生中断？

实证发现的痛点将确定步骤 D 中计划的优先级。

步骤 F — 实施后重新测试

• 委派全新的子智能体（不受改造上下文的影响）走一遍变更后的工作流
• 可衡量的前后对比值：配置时间、错误率、手动步骤数量、构建时间
• 防回归检查：变更后现有工作流是否仍正常运行？
• 如果没有可衡量的改进或出现回归：回滚改造或重新调整

反模式（严格禁止）

反模式	损害	解药
仅搜索插入点而非阅读文档	产生并行标准	完整执行步骤 A
1:1 硬套“来自 X 的最佳实践”	不兼容	步骤 D 进行功能等效对比
创建新文件而不检查现有规范	内容重复（例如 NOTICE.md ↔ THIRD_PARTY_LICENSES.txt）	步骤 A + 步骤 D
无实证依据地自顶向下规划	解决方案偏离实际痛点	在确定计划前执行步骤 E
不测试自己的变更	未检测到回归错误	使用全新的智能体执行步骤 F
状态不明确时“稍后澄清”	用户随后才发现冲突	不确定时，再次与用户共同复核步骤 D

案例研究 — NOTICE.md 事件

任务： 在多个主题流水线（软件、研究、游戏）中实施流水线改进。

错误： 跳过了步骤 A — 仅搜索插入点，而没有阅读完整的规范文件。

后果： 在 7 个文件中引入 NOTICE.md 作为“新许可证文件”，尽管 THIRD_PARTY_LICENSES.txt + 自定义许可证生成器（围绕 pip-licenses 的包装器）已经建立 — 并已记录在流水线的 GitHub 规范（必选文件 + 许可证检查清单）中。所有软件项目此前均已包含 THIRD_PARTY 文件。

发现： 仅在用户质问后才被发现（“我很确定我们之前已经有权限/许可证管理了”）。

纠正： 从项目模板中删除了 NOTICE.md，调整了另外 6 个文件，改为引用现有的许可证生成器而非 pip-licenses。

教训： 如果完整执行了步骤 A，冲突在写入前就会被检测出来。

经验法则

1. 对于“改进流水线”，首先阅读的时间要与编写的时间一样长。
2. 在没有证明不存在现有标准之前，绝不建立新标准。
3. 使用现有的工具/包装器，而非新建并行的工具。
4. “机械堆砌”通常比“扩展现有内容”更糟糕。
5. 在发生冲突时回滚永远优于维护两套并行标准。

完成检查清单

在将流水线改造报告为“已完成”之前：

• 步骤 A：是否已阅读所有相关的根文档？
• 步骤 B：是否用 1-2 句话阐明了流水线目的？
• 步骤 C：是否勾勒了理想蓝图（5-10 点）？
• 步骤 D：是否有带表格的差距分析（保留什么 / 扩展什么 / 新建什么 / 废除什么）？
• 步骤 E：是否核实了实证数据（Bug、教训、自测、用户访谈）？
• 计划是否已与用户达成一致？
• 步骤 F：是否使用全新的子智能体进行了测试 — 改进是否可衡量？
• 是否未引入并行标准？
• 发生冲突时：是否已回滚或坦诚说明情况？

最佳项目文件夹结构（适用于项目文件夹优化器）

当本 Skill 应用于单个项目文件夹时，以下组合建议可作为理想参考（步骤 C）：

Anthropic 标准 (Claude Code)

文件/文件夹	功能
CLAUDE.md（根目录）	由 Claude Code 自动加载，包含项目特定指令
.claude/settings.json	权限、环境变量、模型选择（提交至 Git）
.claude/settings.local.json	本地重写（切勿提交，添加到 .gitignore）
.claude/commands/*.md	自定义斜杠命令
.claude/agents/*.md	自定义子智能体
.claude/skills/<name>/SKILL.md	项目 Skills

您自己的项目文档模板（推荐）

如果您维护自己的项目文档模板（例如在 <your-workspace>/_templates/project-docs/ 下），三种构建配置文件大有裨益。示例划分：MINIMAL（最小化） 提供会话核心集，包含 7 个根文件（AGENTS.md、CLAUDE.md、README.md、START.md、STATE.md、TODO.md、DONE.md）加上 _tools/。STANDARD（标准） 增加了 CHANGELOG.md、DECISIONS.md 和 PATTERNS.md。FULL（完整） 扩展至 14 个根文件，并额外增加了 ARCHITECTURE.md、WORKFLOWS.md、TOOLS.md、GLOSSARY.md 以及 workflows/ 和 .github/。

→ 使用此类模板作为新项目的基底（复制而非手动创建）。

特定流水线的补充内容（示例）

根据流水线的不同，还会增加其他强制性文件 — 典型模式：

• 软件项目： LICENSE、CODE_OF_CONDUCT.md、SECURITY.md、CONTRIBUTING.md、THIRD_PARTY_LICENSES.txt（生成的）、pyproject.toml/requirements.txt、流水线中央发布注册表中的条目。→ 如果可用：使用流水线的 cookiecutter 模板。
• 研究项目： 概念文档、行动计划、出版计划、归档/源码/结果/数据文件夹（_archive/、_sources/、_results/、_data/）、用于 LaTeX 的 paper/。对于推导证明项目：包含证明链和状态的证明笔记文件。
• 游戏项目： 引擎的项目清单和工具链文件（例如对于 Roblox/Rojo：default.project.json、rokit.toml、wally.toml、selene.toml）、游戏设计文档、根据引擎规范设立的 src/{server,client,shared}/。

完整细节参考

→ 参阅本 Skill 文件夹中的 references/optimal-project-structure.md（德文）。包含：

• 示例 settings.json（Anthropic 模式）
• 必选 .gitignore 条目
• 反模式（不属于项目文件夹的内容）
• 按流水线类型推荐的工作流（软件/研究/游戏）
• 文档文件的 YAML 标头规范
• 自动检查草图

相关 Skills（何时使用其他 Skill 代替本 Skill？）

Skill	何时使用
project-onboarding	将外部现有仓库导入您自己的系统
Project bootstrapper（若可用）	在现有流水线中创建新项目（绿地开发，无需重构）
Pipeline bootstrapper（若可用）	创建全新的流水线（罕见情况）
System onboarding（若可用）	配置一台新机器

pipeline optimizer 负责改造，而非新建或导入。如果您的 Skill 集合包含 Skill 索引，请在其中搜索匹配的引导（bootstrapping）Skills。

交叉引用

• 细节参考：references/optimal-project-structure.md（在本 Skill 文件夹中）
• Anthropic Claude Code 文档：https://docs.claude.com/en/docs/claude-code
• 若可用：全局用户规则（例如您 ~/CLAUDE.md 中的“改造”章节）和特定流水线的技术栈描述

作用域选择：流水线 vs. 项目文件夹

如果不清楚指的是哪个作用域，请在步骤 A 前进行明确：

线索	作用域
“改进整个软件流水线”	流水线
“清理工具 X 的文件夹”	项目文件夹
“同步中央发布注册表”	流水线（中央资产）
“重构游戏 Y 中的 AssetBuilder”	项目文件夹
“在整个流水线范围内引入检查规范”	流水线
“在项目 Z 中创建检查文件”	项目文件夹

在项目文件夹作用域下，还需始终简要检查父流水线的规范（扩展的步骤 A），以确保干预措施与流水线保持兼容。

---

更新日志

1.2.0 (2026-06-13)

• 首次发布于 Skill 库：个人路径、具体的流水线/项目名称以及对私有 Skill 的引用均替换为通用示例；流程本身（6个步骤、反模式、案例研究、检查清单）保持不变

1.1.1 (2026-06-01) 及更早版本

• 内部版本（私有 Skill 目录，发布之前）