pc-engineering-adoption
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseEngineering adoption
工程落地
The deliverable is the standard running in the repository: gates that fail a pull request, and the
six facets the CI publishes from the default branch. A dashboard is optional and comes after.
Read before you add anything. Two different
things produce engineering signals, they come from two different places, and mixing them is the
failure this skill exists to prevent.
references/producers.md交付成果是标准在仓库中实际运行:能够使 pull request 失败的工程门禁,以及 CI 从默认分支发布的六个 facet。仪表板是可选的,并在后续阶段实施。
在添加任何内容之前,先阅读 。有两类不同的事物会产生工程信号,它们来自不同来源;这个 skill 的存在正是为了防止将两者混为一谈。
references/producers.md1. Interview
1. 访谈
Read the repository first, then ask one decision per call with the host's question tool, following
. Every question has a recommendation first, and
the person answers by selecting, not by typing.
references/interview.md- Host: GitHub, Azure DevOps, GitLab, or another. Which system holds the code and runs the CI.
- Scope: everything, or engineering only. Everything means delivery and agent metrics too.
- Standard: the Platform standard (Foundations ), or a generic quality bar the team chooses.
ai/ENGINEERING.md - Modules: which of coverage, complexity, mutation, hygiene, security, SBOM, PR gates and the scorecard to install. This is a multi-select, split into two questions of four, and it offers only what the repository can produce.
- Dashboard and, if one will be built, its look: see step 6.
A decision with several valid answers is never asked with a single-select control. If the tool has no
multi-select, number the options and ask for the numbers.
Finish by printing the plan (host, scope, standard, modules, dashboard, look, files to add) and asking
for a go-ahead. Change nothing before it.
Done when every question is answered or the person said "you decide" and you stated the
recommendation you took, and the plan was confirmed.
先阅读仓库,然后按照 ,使用托管平台的提问工具,每次询问一个决策。每个问题都先给出建议,由对方通过选择而不是输入来回答。
references/interview.md- 托管平台:GitHub、Azure DevOps、GitLab 或其他平台。代码存储在哪里,CI 又在哪里运行?
- 范围:全部内容,还是仅工程内容?全部内容还包括交付和 Agent 指标。
- 标准:Platform 标准(Foundations ),还是由团队自行选择的通用质量基线。
ai/ENGINEERING.md - 模块:选择要安装哪些内容,包括覆盖率、复杂度、变异测试、卫生状况、安全、SBOM、PR 门禁和记分卡。这是一个多选项,应拆成两个各含四个选项的问题,并且只提供仓库能够生成的内容。
- 仪表板;如果需要构建仪表板,还要确定其外观:参见步骤 6。
对于存在多个有效答案的决策,绝不能使用单选控件提问。如果工具不支持多选,请为选项编号,并让对方回复编号。
最后打印计划(托管平台、范围、标准、模块、仪表板、外观、待添加文件),并请求对方确认推进。在获得确认前不要做任何更改。
完成条件:所有问题均已回答,或者对方表示“你来决定”且你说明了所采用的建议,并且计划已得到确认。
2. Pick the shape
2. 选择落地形态
| Host | Scope | What to do |
|---|---|---|
| GitHub | everything | Stop. This is not an adoption: it is one entry in an existing Project Health instance. Follow the add-project skill in that repository, or ask whoever runs it |
| GitHub | engineering only | Continue to step 3 on the family template, then step 6 |
| Any other | either | Continue to step 3 with host wiring, then step 6 only if they want a dashboard |
Anything except the first row means this repository needs its own CI wiring, because no family
template exists for that host.
Done when you have named the row and read the reference it points at.
| 托管平台 | 范围 | 操作 |
|---|---|---|
| GitHub | 全部内容 | 停止。这不是一次采用,而是向现有的 Project Health 实例添加一个项目。请遵循该仓库中的 add-project skill,或询问其运行维护者 |
| GitHub | 仅工程内容 | 使用家族模板继续步骤 3,然后执行步骤 6 |
| 其他平台 | 任意 | 完成托管平台接线后继续步骤 3;仅在对方需要仪表板时执行步骤 6 |
除第一行外,其他情况都意味着该仓库需要自己的 CI 接线,因为托管平台不存在对应的家族模板。
完成条件:已确定所处行,并已阅读该行指向的参考资料。
3. Put the producer in the repository
3. 将 producer 放入仓库
The producer reads report files that the build already writes (Cobertura XML, ,
, , , , a CycloneDX BOM). It never calls a
host API, so the same script works everywhere; only the wiring differs.
coverage-final.jsoneslint.jsonjscpd-report.jsonsemgrep.jsontrivy.jsonVendoring rule, in this order:
- If the repository is a Copier consumer (exists), the producer belongs to a platform-owned path in
.copier-answers.yml, and it arrives with.platform/manifest. Do not copy it into the tree by hand.copier update - Otherwise vendor ,
scripts/engineering-excellence.mjs, the schema copy and the gates it needs, with a header pointing back to the source. Record the commit it came from.scripts/lib/
Write down which rule you used, in the pull request or in the repository's decisions folder.
Done when the script runs locally against a real report and writes a that
validates against the vendored copy of the facet schema.
<facet>.jsonproducer 读取构建流程已经生成的报告文件(Cobertura XML、、、、、、CycloneDX BOM)。它绝不会调用托管平台 API,因此同一脚本可以在任何环境运行;不同之处仅在于接线方式。
coverage-final.jsoneslint.jsonjscpd-report.jsonsemgrep.jsontrivy.json内置(vendoring)规则按以下顺序执行:
- 如果仓库是 Copier consumer(存在 ),则 producer 应位于
.copier-answers.yml中由平台维护的路径下,并通过.platform/manifest引入。不要手动将其复制到目录树中。copier update - 否则,内置 、
scripts/engineering-excellence.mjs、schema 副本及其所需的门禁,并添加指回来源的标头。记录其来源 commit。scripts/lib/
在 pull request 或仓库的 decisions 目录中记录所采用的规则。
完成条件:脚本能够使用真实报告在本地运行,并生成符合内置 facet schema 校验要求的 。
<facet>.json4. Wire the host
4. 接入托管平台
- GitHub: the family template already runs the gates. Facets go in a separate workflow file that
reads the reports its CI uploaded, or in after taking ownership of that file. See
app-ci.ymlfor what taking ownership costs.references/producers.md - Azure DevOps: .
references/azure-pipelines.md - GitLab: .
references/gitlab-ci.md
Only the modules chosen in the interview, and of those only the facets the repository can actually
produce. Two or three is a good first release; six is rare, and a facet invented from a tool that
does not run is worse than a missing one. If a chosen module turns out to have no input, say so and
drop it from the plan instead of faking it.
Done when one run on the default branch published the chosen facets, and a pull-request run
published none.
- GitHub:家族模板已经运行门禁。Facet 应放在单独的工作流文件中,用于读取其 CI 上传的报告;也可以在接管 后放入其中。有关接管成本,参见
app-ci.yml。references/producers.md - Azure DevOps:参见 。
references/azure-pipelines.md - GitLab:参见 。
references/gitlab-ci.md
仅实施访谈中选定的模块;其中也仅启用仓库实际能够生成的 facet。首次发布选择两到三个通常较为合适,六个较少见;根据未实际运行的工具臆造 facet,比暂缺一个 facet 更糟。如果选定模块没有输入,应明确说明并从计划中移除,而不是伪造数据。
完成条件:在默认分支上的一次运行中发布了选定 facet,并且在 pull request 运行中没有发布 facet。
5. Verify
5. 验证
- Upload happens on the default branch and on a failed gate, never only on success. A drop is the sample most worth keeping.
- Every facet names this repository in and this branch in
repo; a mismatch is ignored by the consumer and must be ignored, not papered over.ref - The gates fail a pull request that breaks them, and the facets still upload. Facets never gate; the repository's own CI decides what fails.
- is the one the consumer knows. An unknown version is ignored by design, so bumping it without the consumer is a silent data loss.
schemaVersion - One deliberate failure is recorded: break a gate on a branch, confirm the facet still exists, and confirm the dashboard or the reader shows the drop rather than a zero.
- Each module the person selected is accounted for: installed and verified, or dropped with the reason. Nothing selected is silently missing from the result.
Done when every line above is checked against a real run, not against the workflow file.
- 上传应同时发生在默认分支和门禁失败时,绝不能只在成功时上传。一次 drop 失败样本最值得保留。
- 每个 facet 都要在 中标明当前仓库,并在
repo中标明当前分支;消费端会忽略不匹配的数据,因此必须忽略,而不能掩盖问题。ref - 违反门禁的 pull request 应失败,同时 facet 仍需上传。Facet 从不充当门禁;失败条件由仓库自身的 CI 决定。
- 必须是消费端已知的版本。未知版本会按设计被忽略,因此在未同步更新消费端的情况下提升版本,会造成静默数据丢失。
schemaVersion - 记录一次故意制造的失败:在分支上破坏门禁,确认 facet 仍然存在,并确认仪表板或读取器显示 drop,而不是零值。
- 对方选择的每个模块都必须有明确结论:已安装并验证,或已移除并记录原因。结果中不得有任何选定模块被静默遗漏。
完成条件:上述每一项均已通过真实运行进行验证,而不是仅检查工作流文件。
6. The dashboard, if they asked for one
6. 如对方要求,则构建仪表板
Read . It covers the four ways to publish. A
non-GitHub host can now write the month files with , so option 3 is a commit
rather than a piece of work; what it cannot do is collect deployments, agents or pull requests.
references/publishing.mdpnpm facet-store addDone when the person knows which publishing path they have, and what remains to build for the
other one.
If a site will be built, its experience is Project Health's and its identity is the person's. Read
, ask the look question of the interview
(Project Health's palette, a brand they provide, a site to take inspiration from, or colours by
hand), and apply the identity as tokens only. Open the result in a browser, in both themes and at
phone width, and run the checklist in that file before you call it finished.
references/dashboard-ux.mdDone when the site renders, matches that checklist, and the person has seen it in a browser.
阅读 。其中介绍了四种发布方式。非 GitHub 托管平台现在可以使用 写入每月文件,因此方案 3 只需执行一次 commit,无需额外开发;但它无法收集部署、Agent 或 pull request 数据。
references/publishing.mdpnpm facet-store add完成条件:对方了解当前采用的发布路径,以及另一条路径仍需构建的内容。
如果要构建站点,其用户体验应沿用 Project Health,视觉身份则采用对方的品牌。阅读 ,询问访谈中的外观问题(采用 Project Health 的配色、对方提供的品牌、参考某个站点,或手动指定颜色),并且仅以 design tokens 应用该视觉身份。在浏览器中以两种主题和手机宽度打开结果,并运行该文件中的检查清单,之后才能宣布完成。
references/dashboard-ux.md完成条件:站点能够正常渲染,符合检查清单要求,并且对方已在浏览器中查看过。
What "done" does not mean
“完成”并不意味着什么
A green pipeline is not adoption. Every facet degrades to an absent block with a reason when its
input is missing, so a run that published nothing can still be green. Adoption is the run that
produced a number somebody checked against the tool that measured it.
绿色的 pipeline 并不代表已经完成采用。输入缺失时,每个 facet 都会降级为带原因的缺失区块,因此即使一次运行没有发布任何 facet,pipeline 仍可能显示为绿色。真正的采用,是某次运行产生了一个数字,并且有人使用测量它的工具核对了该数字。