Back to Details

context-coverage

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

context-coverage — audit agent-context coverage across repos

context-coverage — 跨仓库审计Agent上下文覆盖情况

Answers one question: across the repos being worked on, where does agent context (CLAUDE.md, AGENTS.md, /rules/, skills) line up with the code — and where is it missing, thin, stale, or oversized?
No invented composite scores. The report shows only directly-measured numbers — LOC, commit dates, context line counts, LOC-per-context-line, and commits-since-context (from real git history in both modes) — and turns them into signal you can act on:
  • Things to check — a short (≈3–10) ranked list of specific, number-backed observations, each framed as worth a look, not a verdict: context that lags the code (N commits since it was last edited), thin coverage (LOC per context line), an oversized (>300-line) CLAUDE.md, a large repo with no per-area context, skills with no root file.
  • Per-repo detail — for each repo: the raw metric strip, where its context files live, and a folder tree — every directory sized by its LOC, colored by whether a context file governs it and how thinly.
  • The numbers — a plain table of everything measured, side by side.
Only active repos are analyzed — a commit within the last 90 days (
--active-days
, 
0
= all), matching the AI-SDLC maturity model's "active repos" denominator. Use 
--repos "a,b,c"
 to analyze only specific repos (fast iteration; forces them in scope). The whole skill folder is self-contained and portable — runs on an org in a few minutes.
回答一个核心问题：在当前处理的仓库中，Agent上下文（CLAUDE.md、AGENTS.md、/rules/、技能）与代码的匹配情况如何——哪些地方存在缺失、覆盖不足、过时或文件过大的问题？
无虚构综合评分。报告仅展示直接测量的数据——代码行数（LOC）、提交日期、上下文行数、每行上下文覆盖的代码行数、上下文更新后的提交次数（两种模式均基于真实Git历史），并将这些数据转化为可执行的信号：
  • 待检查事项——一份简短（约3-10条）的排名列表，包含具体、有数据支撑的观察结果，每条结果均表述为「值得关注，而非定论」：滞后于代码的上下文（上次编辑后已提交N次代码）、覆盖不足（每行上下文覆盖的代码行数）、过大的CLAUDE.md文件（超过300行）、无分区上下文的大型仓库、无根文件的技能。
  • 单仓库详情——针对每个仓库：原始指标条、上下文文件的存储位置，以及文件夹树——每个目录按代码行数标注大小，根据是否有上下文文件管理及覆盖程度着色。
  • 数据表格——将所有测量数据整理为清晰的对比表格。
仅分析活跃仓库——过去90天内有提交记录的仓库（可通过
--active-days
参数调整，
0
表示分析所有仓库），符合AI-SDLC成熟度模型中「活跃仓库」的定义。使用**
--repos "a,b,c"
**参数可仅分析指定仓库（迭代速度快，强制纳入分析范围）。整个技能文件夹独立且可移植——分析一个组织仅需数分钟。

When to use

使用场景

Trigger on: "audit context coverage", "which repos are missing CLAUDE.md", "how good is our context across the org", "where is our agent context thin/stale/missing", "/context-coverage". Also good as a periodic org health check.
触发场景：「审计上下文覆盖情况」、「哪些仓库缺少CLAUDE.md」、「我们组织的上下文质量如何」、「Agent上下文在哪里存在不足/过时/缺失问题」、「/context-coverage」。也适合作为定期的组织健康检查工具。

Two ways to run

两种运行方式

Both produce the same JSON shape, so the same renderer works on either.
两种方式生成的JSON格式一致，因此可使用同一渲染器处理。

Mode A — a local folder of clones (full fidelity, recommended)

模式A——本地克隆文件夹（完整保真度，推荐）

Real LOC, full commit history, nested context, context freshness vs code churn. Needs 
git
on PATH.
bash
uv run python scripts/collect.py --dir <folder-of-repos> --out coverage-data.json
uv run python scripts/render.py coverage-data.json --out coverage-report.html
--dir
scans every git repo that is an immediate subdirectory of the folder.
可获取真实代码行数、完整提交历史、嵌套上下文、上下文新鲜度与代码变更的对比。需要将
git
添加到系统PATH中。
bash
uv run python scripts/collect.py --dir <folder-of-repos> --out coverage-data.json
uv run python scripts/render.py coverage-data.json --out coverage-report.html
--dir
参数会扫描指定文件夹下的所有直接子目录中的Git仓库。

Mode B — a whole GitHub org, no clone (fast, needs 
gh
)

模式B——整个GitHub组织，无需克隆（快速，需要gh CLI）

Enumerates the org with 
gh repo list
, then inspects each repo through the GitHub trees/commits/contents API — no clone. Requires an authenticated 
gh
(
gh auth status
; scope 
repo
+ 
read:org
). LOC is estimated from blob bytes (flagged with 
*
in the report).
bash
uv run python scripts/collect.py --org <org-or-user> --out coverage-data.json
uv run python scripts/render.py coverage-data.json --out coverage-report.html
On this user's machine, always invoke Python as 
uv run python
(bare 
python
hits the Windows Store stub). The scripts are pure standard library, so on any other machine 
python3 scripts/collect.py …
works with no install.
通过
gh repo list
枚举组织，然后通过GitHub trees/commits/contents API检查每个仓库——无需克隆。需要已认证的
gh
CLI（执行
gh auth status
验证；权限范围需包含
repo
+ 
read:org
）。代码行数（LOC）通过Blob字节数估算（报告中会标注
*
）。
bash
uv run python scripts/collect.py --org <org-or-user> --out coverage-data.json
uv run python scripts/render.py coverage-data.json --out coverage-report.html
在当前用户的机器上，需始终以
uv run python
方式调用Python（直接使用
python
会触发Windows Store stub）。脚本基于纯标准库开发，因此在其他机器上可直接使用
python3 scripts/collect.py …
运行，无需额外安装依赖。

How to run it (the recipe)

运行步骤（操作指南）

  1. Pick the target. Ask the user (or infer): a local folder of clones, or a GitHub org/user login. Local mode is richer; org mode needs no clones.
  2. Collect. Run 
    collect.py
    with 
    --dir
    or 
    --org
    . Progress prints to stderr, one line per repo. Org mode scans repos in parallel (
    --jobs
    , default 8) — a ~37-repo org takes ~20s (the heaviest repo is the long pole); 
    --jobs 1
    forces sequential. Local mode is seconds.
  3. Render. Run 
    render.py
    on the JSON to get the HTML.
  4. Show it. Open the HTML, or publish it with the Artifact tool for a shareable link (self-contained and CSP-safe — inline CSS/JS, no external assets). Then give the user the top 2–3 things to check in chat, with their numbers.
Do not paste the raw JSON at the user. The HTML is the deliverable; summarize the takeaways in prose.
  1. 选择目标：询问用户（或自行推断）：是本地克隆文件夹，还是GitHub组织/用户账号。本地模式功能更丰富；组织模式无需克隆仓库。
  2. 收集数据：使用
    --dir
    或
    --org
    参数运行
    collect.py
    。进度信息会输出到stderr，每个仓库一行。组织模式会并行扫描仓库（
    --jobs
    参数，默认值为8）——一个包含约37个仓库的组织需耗时约20秒（最大的仓库是耗时瓶颈）；使用
    --jobs 1
    可强制串行扫描。本地模式仅需数秒。
  3. 生成报告：使用
    render.py
    处理JSON数据，生成HTML报告。
  4. 交付报告：打开HTML报告，或通过Artifact工具发布以生成可共享链接（报告独立且符合CSP安全标准——内置CSS/JS，无外部资源）。然后在对话中向用户汇报排名前2-3的待检查事项及对应数据。
请勿向用户粘贴原始JSON数据。HTML报告是最终交付物；需用文字总结关键结论。

What it measures (per repo)

测量维度（单仓库）

Size/activity: LOC (code files only, 
.gitignore
-respecting via 
git ls-files
), file count, commits in the last 90 days, days since last commit, age, contributors. Context inventory: root + nested 
CLAUDE.md
/ 
AGENTS.md
(with per-file line counts), 
.cursorrules
/ 
.github/copilot-instructions.md
, 
/rules/
dirs, 
.claude/skills
count (real ones only), commands, and tool "surfaces" (
.claude
/ 
.cursor
/ 
.gemini
/ …). Per-folder structure: a pruned directory tree with LOC per folder, plus every context file's location and size (the "anchors"), so the report can compute which folders a given CLAUDE.md actually governs and how thinly (LOC per context line) — this powers the drill-down and the folder-level problem areas. Freshness: when context was last touched (git) and how many code commits landed since.
Vendored directories are pruned everywhere (
node_modules
, 
.venv
, 
site-packages
, 
dist
, 
build
, 
vendor
, 
target
, …), so a CLAUDE.md or skill that ships inside a dependency never inflates the numbers. This matters — without it, a repo with zero real skills can look context-rich because a dependency bundles one.
规模/活跃度：代码行数（仅统计代码文件，通过
git ls-files
遵守
.gitignore
规则）、文件数量、过去90天内的提交次数、上次提交距今天数、仓库存续时长、贡献者数量。 上下文清单：根目录及嵌套的
CLAUDE.md
/
AGENTS.md
（含每个文件的行数）、
.cursorrules
/
.github/copilot-instructions.md
、
/rules/
目录、
.claude/skills
的有效数量、命令及工具「入口」（
.claude
/
.cursor
/
.gemini
/…）。 文件夹结构：经过修剪的目录树，包含每个文件夹的代码行数，以及每个上下文文件的位置和大小（即「锚点」），以便报告计算指定CLAUDE.md实际管理的文件夹范围及覆盖程度（每行上下文覆盖的代码行数）——这是深入分析和定位文件夹级问题的核心依据。 新鲜度：上下文文件的最后修改时间（来自Git），以及此后的代码提交次数。
所有第三方依赖目录均会被修剪（
node_modules
、
.venv
、
site-packages
、
dist
、
build
、
vendor
、
target
等），因此依赖包中附带的CLAUDE.md或技能不会影响统计数据。这一点至关重要——若未做修剪，一个本身无真实技能的仓库可能因依赖包附带技能而被误判为上下文丰富。

Which repos get analyzed

仓库筛选规则

Three ways to choose the set — all composable with exclusions:
  1. Self-select — analyze exactly the repos you name (activity cutoff ignored; works in 
    --dir
    too):
    bash
    uv run python scripts/collect.py --org ACME --repos "platform-core,billing,web"
  2. Commit cutoff (default) — every repo in the org with a commit in the last N days:
    bash
    uv run python scripts/collect.py --org ACME                  # last 90 days (default)
uv run python scripts/collect.py --org ACME --active-days 30
uv run python scripts/collect.py --org ACME --active-days 0  # no cutoff, all repos
    Obvious non-projects (archived, forks, empty < 50 LOC, and scratch/demo/test-named repos) are dropped automatically; adjust with exclusions/inclusions.
  3. Exclusions & inclusions — layer onto either mode, persistent and portable:
    bash
    uv run python scripts/collect.py --org ACME --exclude "*-demo,legacy-*,*sandbox*"
uv run python scripts/collect.py --org ACME --include "keep-this-inactive-repo"  # force in, ignores cutoff
uv run python scripts/collect.py --org ACME --overrides overrides.json           # reuse a saved file
    overrides.json
    = 
    {"include": ["core"], "exclude": ["*-demo","legacy-*"]}
    . Name globs, case-insensitive; exclude wins over include.
In the report: a "Which repos to analyze" panel at the top lets the reader re-dial scope live — commit-cutoff presets (30d/90d/6mo/1yr/any), per-repo checkboxes, and Export selection (writes the 
--repos
command + an overrides file for the next run). Choices persist in the browser.
Exact LOC (
--clone
): org mode estimates LOC from blob bytes (flagged 
*
). Add 
--clone
to clone each selected repo and measure LOC, nested context, and freshness exactly (reuses the local scanner). Slower, so pair it with 
--repos
or a tight cutoff — for a focused set where the numbers need to be right.
三种选择仓库集的方式——均可与排除规则组合使用：
  1. 指定仓库——仅分析您命名的仓库（忽略活跃度阈值；也适用于
    --dir
    模式）：
    bash
    uv run python scripts/collect.py --org ACME --repos "platform-core,billing,web"
  2. 提交时间阈值（默认）——组织中过去N天内有提交记录的所有仓库：
    bash
    uv run python scripts/collect.py --org ACME                  # 默认过去90天
uv run python scripts/collect.py --org ACME --active-days 30
uv run python scripts/collect.py --org ACME --active-days 0  # 无阈值，分析所有仓库
    明显的非项目仓库（已归档、分支、代码行数<50的空仓库、命名包含scratch/demo/test的仓库）会被自动排除；可通过排除/包含规则调整。
  3. 排除与包含规则——可叠加到任意模式，规则持久且可移植：
    bash
    uv run python scripts/collect.py --org ACME --exclude "*-demo,legacy-*,*sandbox*"
uv run python scripts/collect.py --org ACME --include "keep-this-inactive-repo"  # 强制纳入，忽略阈值
uv run python scripts/collect.py --org ACME --overrides overrides.json           # 复用已保存的规则文件
    overrides.json
    示例：
    {"include": ["core"], "exclude": ["*-demo","legacy-*"]}
    。支持名称通配符，不区分大小写；排除规则优先级高于包含规则。
报告中的交互功能：顶部的「仓库筛选」面板允许读者实时调整分析范围——提交时间阈值预设（30天/90天/6个月/1年/任意）、单仓库复选框，以及「导出筛选结果」（生成
--repos
命令及覆盖规则文件，供下次运行使用）。筛选选择会在浏览器中持久保存。
精确代码行数（
--clone
参数）：组织模式通过Blob字节数估算代码行数（标注
*
）。添加
--clone
参数可克隆每个选中的仓库，精确测量代码行数、嵌套上下文和新鲜度（复用本地扫描逻辑）。速度较慢，因此建议配合
--repos
参数或严格的时间阈值使用——适用于需要精确数据的聚焦分析场景。

What it flags — direct signals, no composite scores

告警规则——直接信号，无综合评分

Everything shown is a directly-measured count or a plain ratio; there is no invented 0–100 score. The only thresholds live in 
collect.py
's 
MODEL
:
  • LOC per context line = total code LOC ÷ total CLAUDE.md/AGENTS.md lines. Shown only when context is layered (a nested CLAUDE.md or a 
    /rules/
    dir) — with a single root file it's just LOC ÷ root length, so it's suppressed as noise.
  • Commits since context = commits to the default branch since the newest context file was last edited (from git history, in both modes). ≥ 25 → stale.
  • Folder governance (per-repo tree) = a folder's LOC ÷ the lines of its nearest governing context file; a folder over ~450 LOC/line (or with none) is flagged.
  • Oversized file = any single CLAUDE.md / AGENTS.md over 300 lines.
The report leads with a Things to check list (≈3–10 findings, worst-first, framed as worth a look, not a verdict), then per-repo raw metrics and a folder tree, then a grouped table of every number. Tune the 
MODEL
thresholds and re-run.
报告中展示的所有内容均为直接测量的计数或简单比率；无虚构的0-100分评分。唯一的阈值定义在
collect.py
的
MODEL
中：
  • 每行上下文覆盖的代码行数 = 总代码行数 ÷ 总CLAUDE.md/AGENTS.md行数。仅当上下文为分层结构（存在嵌套CLAUDE.md或
    /rules/
    目录）时才会展示——若仅存在单个根文件，该比率仅为总代码行数 ÷ 根文件长度，会被视为无效数据而隐藏。
  • 上下文更新后的提交次数 = 默认分支中，最近一次上下文文件编辑后的代码提交次数（两种模式均基于Git历史）。≥25次 → 过时。
  • 文件夹管理情况（单仓库树） = 文件夹代码行数 ÷ 最近的管理上下文文件行数；代码行数/上下文行数超过约450（或无上下文文件）的文件夹会被标记。
  • 过大文件 = 单个CLAUDE.md/AGENTS.md文件超过300行。
报告开头会展示待检查事项列表（约3-10条结论，按严重程度排序，表述为「值得关注，而非定论」），随后是单仓库原始指标和文件夹树，最后是所有数据的分组表格。可调整
MODEL
中的阈值并重新运行。

Files

文件说明

PathRole
scripts/collect.py
Scanner → 
coverage-data.json
. Stdlib only. 
--dir
(local) or 
--org
(gh).
scripts/render.py
coverage-data.json
→ self-contained HTML report. Stdlib only.
references/metrics.md
Full metric + JSON-field reference, and how to extend the model.
examples/example-report.html
A prebaked walkthrough — 7 synthetic 
acme-corp
repos spanning great (deeply nested CLAUDE.md + many skills) / good / okay / bad / bloated context, plus one inactive (out at the default cutoff) and one auto-excluded. Open it to see the report — and the scope filters — without scanning anything.
examples/generate_example.py
Regenerates the example data (via the real 
collect.py
logic); re-render with 
render.py
after.
路径作用
scripts/collect.py
扫描工具 → 生成
coverage-data.json
。仅依赖标准库。支持
--dir
（本地）或
--org
（gh CLI）模式。
scripts/render.py
将
coverage-data.json
→ 生成独立的HTML报告。仅依赖标准库。
references/metrics.md
完整的指标+JSON字段参考文档，以及扩展模型的方法。
examples/example-report.html
预生成的演示报告——包含7个模拟的
acme-corp
仓库，覆盖从优秀（深度嵌套CLAUDE.md+多技能）/良好/一般/较差/冗余的上下文情况，以及一个默认阈值下的非活跃仓库和一个自动排除的仓库。无需扫描任何内容，直接打开即可查看报告及范围筛选功能。
examples/generate_example.py
重新生成演示数据（基于真实的
collect.py
逻辑）；生成后需用
render.py
重新渲染。

Notes & limits

注意事项与限制

  • Org mode LOC is an estimate (blob bytes ÷ ~38), flagged with 
    *
    . For exact LOC, clone and use 
    --dir
    .
  • Org mode skips total-commit and contributor counts (too many API calls); it uses 
    pushedAt
    for recency and a 90-day commit window.
  • A repo the scanner can't read (no default branch, empty, API error) still appears, with an 
    errors
    note in the JSON.
  • Everything is local/offline except the 
    gh
    calls in org mode. No data leaves the machine.
  • 组织模式的代码行数为估算值（Blob字节数 ÷ 约38），报告中会标注
    *
    。如需精确代码行数，请克隆仓库并使用
    --dir
    模式。
  • 组织模式会跳过总提交次数和贡献者数量统计（API调用次数过多）；使用
    pushedAt
    判断仓库新鲜度，并采用90天的提交窗口。
  • 扫描工具无法读取的仓库（无默认分支、空仓库、API错误）仍会出现在报告中，JSON数据中会包含
    errors
    注释。
  • 除组织模式下的gh CLI调用外，所有操作均为本地/离线执行。数据不会离开本地机器。