readme-maintainer

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

README Maintainer

README维护者

Goal

目标

Produce README files that are fast to skim, technically accurate, and explicit about quality signals. Prefer omission over guessing.

生成易于快速浏览、技术准确且明确展示质量指标的README文件。优先省略不确定的内容，而非猜测。

Workflow

工作流程

Collect evidence-backed facts.
Verify anything unclear before writing badges or version numbers.
Draft or update README with a compact section order.
Surface test layers and CI status immediately.
Run a final accuracy pass.

收集有证据支撑的事实。
在编写徽章或版本号之前，先验证所有不明确的信息。
以紧凑的章节顺序起草或更新README。
立即突出展示测试层级和CI状态。
进行最终的准确性检查。

1) Collect Facts

1) 收集事实

Run the bundled scanner first:

bash

python ~/.codex/skills/readme-maintainer/scripts/readme_facts.py --repo . --format markdown > /tmp/readme-facts.md
python ~/.codex/skills/readme-maintainer/scripts/readme_facts.py --repo . --format json > /tmp/readme-facts.json

Use

/tmp/readme-facts.json

as the source of truth for detected runtime, tools, deployment, external services, API surface, and test/CI gaps.

首先运行内置的扫描器：

bash

python ~/.codex/skills/readme-maintainer/scripts/readme_facts.py --repo . --format markdown > /tmp/readme-facts.md
python ~/.codex/skills/readme-maintainer/scripts/readme_facts.py --repo . --format json > /tmp/readme-facts.json

将

/tmp/readme-facts.json

作为检测到的运行时环境、工具、部署方式、外部服务、API接口以及测试/CI缺口的事实来源。

2) Verify Badge Inputs

2) 验证徽章输入

For every versioned badge, confirm:

Exact source file is known.
Version precision is
```
exact
```
or clearly range-based.
Badge value matches the repo state now.

If exact version is unknown, do not invent a number. Use an unversioned badge or omit it.

对于每个带版本的徽章，确认：

明确知晓对应的源文件。
版本精度为
```
exact
```
（精确）或明确基于范围。
徽章数值与当前仓库状态一致。

如果确切版本未知，请勿编造数字。使用无版本的徽章或直接省略。

3) Use a Compact README Shape

3) 使用紧凑的README结构

Keep the document short and stable. Default order:

Title + one-line summary.
Badge block (grouped).
What it does (3-7 bullets).
How it works (short architecture summary).
Quick start.
Testing and CI matrix.
Deployment and external services.
Copyright and license.

If the project has callable APIs, include a short API section and always include an

e2e api

line in the testing matrix.

保持文档简短且结构稳定。默认章节顺序：

标题 + 一行摘要。
徽章块（分组展示）。
功能介绍（3-7个要点）。
工作原理（简短的架构概述）。
快速开始。
测试与CI矩阵。
部署与外部服务。
版权与许可证。

如果项目包含可调用的API，需添加简短的API章节，并在测试矩阵中始终包含

e2e api

条目。

4) Testing and CI Must Be Up Front

4) 测试与CI信息必须前置

Use this table near the top half of README:

Layer	Present	Tooling	Runs in CI
unit	yes/no	tool list or `none`	yes/no
integration	yes/no	tool list or `none`	yes/no
e2e api	yes/no	tool list or `none`	yes/no
e2e web	yes/no	tool list or `none`	yes/no

Rules:

Show all four rows every time.
Keep
```
no
```
visible; do not hide missing layers.
If APIs are exposed and
```
e2e api
```
is missing, call it out in plain text immediately below the table.

在README的上半部分使用如下表格：

层级	是否存在	工具	是否在CI中运行
单元测试	是/否	工具列表或 `none`	是/否
集成测试	是/否	工具列表或 `none`	是/否
端到端API测试	是/否	工具列表或 `none`	是/否
端到端Web测试	是/否	工具列表或 `none`	是/否

规则：

每次都要展示全部四行。
保留
```
no
```
标识，不要隐藏缺失的测试层级。
如果项目暴露了API但缺失
```
e2e api
```
测试，需在表格下方立即用明文指出。

5) Badge Rules

5) 徽章规则

Group badges by purpose, not alphabetically: stack, tooling, testing/ci, deploy/license.
Keep badge count practical; drop low-value badges.
Prefer official docs links for each badge target.
Include license badge only when a license file or explicit license metadata exists.

Use

references/readme-patterns.md

for compact badge grouping and section templates.

按用途分组徽章，而非按字母顺序：技术栈、工具、测试/CI、部署/许可证。
保持徽章数量实用，移除低价值的徽章。
优先使用每个徽章目标的官方文档链接。
仅当存在许可证文件或明确的许可证元数据时，才添加许可证徽章。

可参考

references/readme-patterns.md

获取紧凑的徽章分组方式和章节模板。

6) Final Quality Gate

6) 最终质量检查

Before finalizing README changes:

Re-run
```
readme_facts.py
```
if code changed during editing.
Confirm every numeric badge value is source-backed.
Call out missing tests/CI explicitly.
Include copyright and license lines when available.
Keep prose skimmable: short paragraphs, bullets, and tables.

在确定README的修改内容之前：

如果编辑期间代码有变更，重新运行
```
readme_facts.py
```
。
确认每个带数字的徽章数值都有来源支撑。
明确指出缺失的测试/CI环节。
若有相关信息，添加版权与许可证条款。
保持内容易于浏览：使用短段落、要点和表格。