inline-doc-governance

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Inline Doc Governance

内联文档治理

Overview

概述

Use this skill to keep documentation close to the code it explains without creating low-signal comment noise. It combines a deterministic audit for coverage checks with a judgment-based review for contracts, side effects, and "why" comments.

The default posture is repo-agnostic: discover local rules first, skip generated and vendor-owned files, and adapt strictness to the project instead of imposing a universal comment quota.

使用本技能可将文档与所解释的代码紧密结合，同时避免生成低价值的注释冗余。它结合了用于覆盖率检查的确定性审计，以及针对契约、副作用和“原因”注释的基于判断的审查。

默认策略与项目无关：优先发现本地规则，跳过生成文件和供应商所有文件，并根据项目调整严格程度，而非强制统一的注释配额。

Default Recommendation

默认建议

Prefer this baseline for new repos:

Require file headers for repo-owned source files.
Require docs for exported, public, package-visible, cross-boundary, or otherwise important types.
Require function and method contract docs only for public surfaces, cross-module seams, services, stores, adapters, coordinators, resolvers, and side-effectful operations.
Add inline comments only when they explain a decision the code does not make obvious.
Use strict "all types need docs" mode only when the repo has adopted that rule.

If a repo already has stronger rules, follow the repo. If the repo has no rules, propose the baseline and explain the strictness options before making broad edits.

对于新代码库，建议采用以下基准：

要求代码库自有源文件包含文件头。
要求导出、公开、包可见、跨边界或其他重要类型具备文档。
仅要求公开接口、跨模块衔接层、服务、存储、适配器、协调器、解析器和有副作用的操作具备函数与方法契约文档。
仅当注释能解释代码未明确体现的决策时，才添加内联注释。
仅当代码库已采用“所有类型都需要文档”规则时，才启用该严格模式。

如果代码库已有更严格的规则，则遵循现有规则；如果代码库暂无规则，建议先提出上述基准，并在进行大范围编辑前说明严格程度的可选方案。

Trigger Checklist

触发检查清单

Use this skill when any of these are true:

the user asks to audit or improve comment coverage
the user asks to set up repo rules for inline docs or code comments
source files need file headers, type docs, or public API docs
comments are stale, vague, tutorial-style, or restating code
generated-file exclusions need to be made explicit
a PR review asks for more documentation around contracts, side effects, or boundary decisions
a repo is adopting a durable docs/rules policy for comments and inline docs

Skip this skill for prose-only docs work that does not affect code comments, or for one-line code changes where no public surface, boundary, or non-obvious behavior changes.

当出现以下任一情况时，使用本技能：

用户要求审计或提升注释覆盖率
用户要求为内联文档或代码注释设置代码库规则
源文件需要添加文件头、类型文档或公开API文档
注释过时、模糊、教程风格或重复代码内容
需要明确生成文件的排除规则
PR审查要求针对契约、副作用或边界决策补充更多文档
代码库正在为注释和内联文档采用持久化的文档/规则策略

如果是不涉及代码注释的纯文档工作，或是未改变公开接口、边界或非显式行为的单行代码变更，则无需使用本技能。

Workflow

工作流程

1. Discover local rules

1. 发现本地规则

Before auditing or writing comments, inspect the repo for existing guidance:

```
AGENTS.md
```
,
```
CLAUDE.md
```
,
```
GEMINI.md
```
, or similar agent instructions
```
docs/rules/
```
,
```
CONTRIBUTING.md
```
,
```
README.md
```
, package docs, and architecture docs
boundary manifests, module ownership docs, or public API guidance
generated-file rules in codegen docs, lint config, ignore files, or package scripts
language and validation commands from package manifests, Makefiles, CI, or local docs

State what you found and what rule set you will apply. If there are multiple valid strictness levels, recommend one explicitly.

在审计或编写注释前，检查代码库中的现有指导：

```
AGENTS.md
```
、
```
CLAUDE.md
```
、
```
GEMINI.md
```
或类似的Agent说明文档
```
docs/rules/
```
、
```
CONTRIBUTING.md
```
、
```
README.md
```
、包文档和架构文档
边界清单、模块所有权文档或公开API指南
代码生成文档、lint配置、忽略文件或包脚本中的生成文件规则
包清单、Makefile、CI或本地文档中的语言与验证命令

说明你发现的内容以及将采用的规则集。如果存在多个有效的严格级别，需明确推荐其中一个。

2. Choose the policy strictness

2. 选择策略严格程度

Use one of these modes:

```
public
```
- file headers plus docs for exported, public, package-visible, or cross-boundary types. This is the recommended default.
```
all
```
- file headers plus docs for every type declaration. Use only when the repo already prefers high inline-doc coverage.
```
none
```
- file headers only. Use for early adoption or when type-doc coverage would be too noisy.

For new repo setup, use comment-doc-policy-template.md as the starting policy and adapt it to the repo's languages and validation commands.

使用以下模式之一：

```
public
```
- 文件头加上导出、公开、包可见或跨边界类型的文档。这是推荐的默认模式。
```
all
```
- 文件头加上所有类型声明的文档。仅当代码库偏好高内联文档覆盖率时使用。
```
none
```
- 仅保留文件头。适用于早期采用阶段，或类型文档覆盖率会产生过多冗余的场景。

对于新代码库的设置，以comment-doc-policy-template.md作为起始策略，并根据代码库的语言和验证命令进行调整。

3. Run the deterministic audit

3. 执行确定性审计

Run the audit script from the target repo root or against selected paths:

bash

python3 path/to/inline-doc-governance/scripts/audit_inline_docs.py --type-doc-policy public .

Strict mode:

bash

python3 path/to/inline-doc-governance/scripts/audit_inline_docs.py --type-doc-policy all src packages/app/src

Use

--fix

only for mechanical cleanup, such as moving an existing doc above decorators or attributes. It does not invent missing documentation text:

bash

python3 path/to/inline-doc-governance/scripts/audit_inline_docs.py --type-doc-policy public --fix src

The script enforces only deterministic checks:

supported repo-owned source files have a top-of-file header that is not just a tool directive
selected type declarations have docs immediately above the declaration or decorators/attributes
generated, vendor-owned, build-output, and test files are skipped by default

If the script flags generated or third-party code, update the exclusion rules before editing that file.

从目标代码库根目录或针对选定路径运行审计脚本：

bash

python3 path/to/inline-doc-governance/scripts/audit_inline_docs.py --type-doc-policy public .

严格模式：

bash

python3 path/to/inline-doc-governance/scripts/audit_inline_docs.py --type-doc-policy all src packages/app/src

仅在进行机械清理时使用

--fix

，例如将现有文档移至装饰器或属性上方。该参数不会生成缺失的文档文本：

bash

python3 path/to/inline-doc-governance/scripts/audit_inline_docs.py --type-doc-policy public --fix src

该脚本仅强制执行确定性检查：

受支持的代码库自有源文件包含顶部文件头，且不只是工具指令
选定的类型声明在声明或装饰器/属性上方紧邻位置有文档
默认跳过生成文件、供应商所有文件、构建输出和测试文件

如果脚本标记了生成或第三方代码，请先更新排除规则，再编辑该文件。

4. Fix hard failures first

4. 优先修复严重问题

Resolve deterministic failures before adding body comments:

add or strengthen file headers before imports
add type docs immediately above the declaration, decorators, or attributes
move misplaced docs above decorators or attributes when needed
keep comments short and specific

Do not edit generated files or files with generated headers. If a generated file needs different output, change the source or generator.

在添加正文注释前，先解决确定性检查失败的问题：

在导入语句前添加或强化文件头
在类型声明、装饰器或属性上方紧邻位置添加类型文档
必要时将错位的文档移至装饰器或属性上方
保持注释简短且具体

不要编辑生成文件或带有生成头的文件。如果生成文件需要不同的输出，请修改源文件或生成器。

5. Do the semantic pass

5. 执行语义检查

Read only the relevant language reference when needed:

TypeScript and JavaScript: typescript.md
Swift: swift.md
Audit loop: audit-and-fix.md

Look for missing docs the script cannot prove:

public or exported functions and methods missing contract docs
cross-module adapters, stores, services, resolvers, coordinators, and remote sources with weak docs
parameters or return values whose meaning is not obvious from the type
side effects such as network I/O, persistence, file writes, logging, mutation, caching, retries, or task scheduling
boundary, fallback, timeout, ordering, normalization, compatibility, or provider-quirk decisions without a local why-comment

Skip comments that restate syntax. Prefer a better name or smaller helper over a comment when that fully explains the code.

仅在需要时查阅相关语言参考：

TypeScript和JavaScript：typescript.md
Swift：swift.md
审计循环：audit-and-fix.md

查找脚本无法检测到的缺失文档：

缺少契约文档的公开或导出函数与方法
文档薄弱的跨模块适配器、存储、服务、解析器、协调器和远程源
含义无法从类型中明确体现的参数或返回值
副作用，如网络I/O、持久化、文件写入、日志记录、突变、缓存、重试或任务调度
未附带本地“原因”注释的边界、回退、超时、排序、规范化、兼容性或供应商特性决策

跳过重复语法的注释。如果重命名或拆分辅助函数能充分解释代码，优先选择这种方式而非添加注释。

6. Set up repo rules when requested

6. 按要求设置代码库规则

When the user asks to govern documentation coverage or set rules for a repo:

Discover the repo's docs/rules convention.
Propose where the durable rule should live.
Adapt comment-doc-policy-template.md.
Link the new rule from agent guidance only when the repo already uses a central guidance file.
Add the audit command to the repo's validation guidance when it is practical for contributors to run.
Run the narrowest validation command that proves the policy and references are valid.

Do not create repo docs just to satisfy this skill. Add durable policy only when it will guide future contributors.

当用户要求管理文档覆盖率或为代码库设置规则时：

发现代码库的文档/规则约定。
建议持久化规则的存放位置。
调整comment-doc-policy-template.md。
仅当代码库已使用中央指导文件时，才在Agent指导中链接新规则。
当贡献者可实际运行时，将审计命令添加到代码库的验证指南中。
运行最窄范围的验证命令，以证明策略和参考内容有效。

不要仅为满足本技能而创建代码库文档。仅当持久化策略能指导未来贡献者时才添加。

Comment Quality Rules

注释质量规则

Explain why, contract, ownership, side effects, edge cases, or tradeoffs.
Do not narrate the code.
Prefer plain language and active voice.
Keep comments close to the code they describe.
Keep temporary comments traceable with an owner, issue, expiry, or removal condition.
Reference constants by name instead of duplicating values that may drift.
Date or version-gate workaround comments when the workaround is expected to expire.
Remove stale comments while editing the code they describe.

解释原因、契约、所有权、副作用、边缘情况或权衡。
不要叙述代码内容。
优先使用平实语言和主动语态。
保持注释与所描述的代码紧密相邻。
临时注释需可追溯，包含所有者、问题、到期时间或移除条件。
通过名称引用常量，而非复制可能变化的值。
当预期解决方法会过期时，为其添加日期或版本限制注释。
在编辑注释所描述的代码时，移除过时的注释。

Comment Sync Rules

注释同步规则

When changing code, keep nearby comments in the same edit pass:

Read the file header, type docs, method docs, and inline comments before changing behavior.
Update comments whose stated contract, side effect, ownership, fallback, or edge case changed.
Delete comments that no longer match the code.
Do not leave "almost right" comments for a later cleanup pass.
If a change makes a comment unnecessary because the code is now self-explanatory, remove the comment instead of rewriting it.
If a public API change affects docs in another file, update the local caller-facing docs in the same PR.

修改代码时，需在同一编辑流程中更新附近的注释：

在更改行为前，阅读文件头、类型文档、方法文档和内联注释。
更新与已变更的契约、副作用、所有权、回退或边缘情况不符的注释。
删除与代码不再匹配的注释。
不要留下“近乎正确”的注释以待后续清理。
如果变更使注释变得多余（因为代码现在可自我解释），则移除注释而非重写。
如果公开API变更影响其他文件中的文档，需在同一PR中更新本地调用方可见的文档。

Generated File Rules

生成文件规则

Never edit generated files or files with generated headers.

Treat these as generated or vendor-owned unless local repo rules say otherwise:

generated directories such as
```
generated/
```
,
```
Generated/
```
,
```
__generated__/
```
declaration outputs such as
```
.d.ts
```
GraphQL generated Swift files such as
```
*.graphql.swift
```

build outputs such as

dist/

build/

.build/

.next/

DerivedData/

, and

Pods/

vendored code and dependency folders such as
```
node_modules/
```
files whose opening banner says generated, do not edit, do not modify, or generated by

切勿编辑生成文件或带有生成头的文件。

除非本地代码库规则另有说明，否则将以下文件视为生成或供应商所有：

生成目录，如
```
generated/
```
、
```
Generated/
```
、
```
__generated__/
```
声明输出文件，如
```
.d.ts
```
GraphQL生成的Swift文件，如
```
*.graphql.swift
```

构建输出目录，如

dist/

、

build/

、

.build/

、

.next/

、

DerivedData/

和

Pods/

供应商代码和依赖文件夹，如
```
node_modules/
```
开头提示为生成、请勿编辑、请勿修改或由某工具生成的文件

Output Expectations

输出预期

For audit or fix tasks, report:

deterministic audit command and result
file headers or type docs fixed
semantic contract or inline why-comments fixed
deliberate skips, especially generated files
recommended next step if the repo should adopt or tighten a policy

For setup tasks, report:

policy file path created or updated
strictness level selected and why
validation command added or recommended
checks run

对于审计或修复任务，需报告：

确定性审计命令及结果
已修复的文件头或类型文档
已修复的语义契约或内联“原因”注释
刻意跳过的内容，尤其是生成文件
如果代码库应采用或收紧策略，建议的下一步操作

对于设置任务，需报告：

创建或更新的策略文件路径
所选的严格程度及原因
添加或推荐的验证命令
已执行的检查

Bundled Files

捆绑文件

```
scripts/audit_inline_docs.py
```
- deterministic audit and mechanical doc-placement fixer for TypeScript, JavaScript, and Swift files.
```
scripts/test_audit_inline_docs.py
```
- smoke tests for the audit helper.
```
references/audit-and-fix.md
```
- focused audit loop for applying the script and semantic pass.
```
references/typescript.md
```
- TypeScript and JavaScript doc patterns.
```
references/swift.md
```
- Swift doc patterns.
```
references/comment-doc-policy-template.md
```
- repo policy template for durable docs/rules setup.

```
scripts/audit_inline_docs.py
```
- 针对TypeScript、JavaScript和Swift文件的确定性审计与机械文档位置修复工具。
```
scripts/test_audit_inline_docs.py
```
- 审计工具的冒烟测试。
```
references/audit-and-fix.md
```
- 应用脚本和语义检查的聚焦审计循环指南。
```
references/typescript.md
```
- TypeScript和JavaScript文档模式指南。
```
references/swift.md
```
- Swift文档模式指南。
```
references/comment-doc-policy-template.md
```
- 用于持久化文档/规则设置的代码库策略模板。