> 中文 — 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 处理第三方许可证”。现实情况：通过自定义生成器脚本包裹它 → 功能等效，无需干预。

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

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

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

→ 由此制定具体计划：

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

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

步骤 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 目录，发布之前）