Back to Details

repo-hygiene

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

repo-hygiene — Repository Health Check

repo-hygiene — 仓库健康检查

A structured, periodic health check for repositories. Run anytime to detect drift, accumulation of tech debt, and configuration issues before they become problems.
Not a release gate. For pre-release checks, use the 
pre-release
skill instead. This skill is for ongoing maintenance — run it weekly, after major refactors, when onboarding to a repo, or whenever things feel "off".
这是一个结构化的仓库定期健康检查方案。可随时运行，在代码漂移、技术债务累积和配置问题演变为严重故障前及时发现它们。
非发布准入检查。若需预发布检查，请使用
pre-release
技能。本技能用于日常维护——可每周运行一次、大型重构后运行、加入新仓库时运行，或是感觉仓库状态「不对劲」时运行。

When to Use

适用场景

  • Onboarding to a new (or forgotten) repo — "what shape is this in?"
  • Weekly/monthly maintenance sweep
  • After a large refactor or dependency upgrade
  • Before starting a new feature sprint
  • When CI starts failing mysteriously
  • After a team member leaves and you inherit their repo
  • 加入新仓库（或重新接手遗忘已久的仓库）时——「这个仓库当前状态如何？」
  • 每周/每月维护巡检
  • 大型重构或依赖项升级完成后
  • 启动新功能迭代前
  • CI系统出现莫名失败时
  • 团队成员离职后接手其仓库时

Supported Stacks

支持的技术栈

StackPackage managerDetected by
Node.js / TypeScriptnpm
package.json
+ 
package-lock.json
Pythonuv / pip
pyproject.toml
or 
requirements.txt
Gogo modules
go.mod
Detect the stack from the project root. Multiple stacks in one repo is fine — run applicable checks for each. If the stack isn't listed, skip stack-specific checks and run the universal ones (git, CI, docs, security).
技术栈包管理器检测依据
Node.js / TypeScriptnpm
package.json
+ 
package-lock.json
Pythonuv / pip
pyproject.toml
或 
requirements.txt
GoGo Modules
go.mod
从项目根目录自动检测技术栈。单个仓库支持多技术栈——会为每个适用的技术栈运行对应检查。若技术栈未在列表中，则跳过栈专属检查，仅运行通用检查（Git、CI、文档、安全）。

The Workflow

工作流程

Step 0: Detect Project

步骤0：检测项目信息

bash
undefined
bash
undefined

What are we working with?

识别当前项目类型

ls package.json pyproject.toml go.mod 2>/dev/null git rev-parse --show-toplevel

Determine: stack(s), git remote, default branch, CI system (GitHub Actions, GitLab CI, etc.).
ls package.json pyproject.toml go.mod 2>/dev/null git rev-parse --show-toplevel

确定：技术栈、Git远程仓库地址、默认分支、CI系统（GitHub Actions、GitLab CI等）。

Step 1: Dependency Health

步骤1：依赖项健康检查

Node.js / npm

Node.js / npm

#CheckCommandSeverity
D1Known vulnerabilities
npm audit --json
🔴 critical/high = Fix Now, moderate = Fix Soon
D2Outdated dependencies
npm outdated --json
🟡 major bumps = Fix Soon, minor/patch = Info
D3Unused dependencies
npx depcheck --json
🟡 Fix Soon
D4Phantom dependencies (used but undeclared)
npx depcheck --json
→ 
missing
🔴 Fix Now
D5Lockfile freshnessSee below🟡 Fix Soon
D6Duplicate dependencies
npm ls --all --json 2>/dev/null | grep -c '"deduped"'
ℹ️ Info
D5 — Lockfile freshness check:
bash
undefined
编号检查项命令严重程度
D1已知漏洞
npm audit --json
🔴 严重/高危 = 立即修复，中危 = 尽快修复
D2过时依赖项
npm outdated --json
🟡 大版本更新 = 尽快修复，小版本/补丁 = 信息提示
D3未使用依赖项
npx depcheck --json
🟡 尽快修复
D4幽灵依赖项（已使用但未声明）
npx depcheck --json
→ 
missing
字段		🔴 立即修复
D5锁文件新鲜度见下方说明🟡 尽快修复
D6重复依赖项
npm ls --all --json 2>/dev/null | grep -c '"deduped"'
ℹ️ 信息提示
D5 — 锁文件新鲜度检查：
bash
undefined

package.json changed more recently than lockfile?

检查package.json是否比lockfile更新

LOCK_DATE=$(git log -1 --format=%ct -- package-lock.json 2>/dev/null || echo 0) PKG_DATE=$(git log -1 --format=%ct -- package.json 2>/dev/null || echo 0) if [ "$PKG_DATE" -gt "$LOCK_DATE" ]; then echo "⚠️ package.json modified after lockfile — run npm install" fi

**How to fix:**

- D1: `npm audit fix` for compatible fixes; `npm audit fix --force` for breaking (review changes). For stubborn advisories: check if the vuln is reachable, or override in `package.json` `overrides`.
- D2: `npm update` for minor/patch; `npm install <pkg>@latest` for major (check changelogs).
- D3: `npm uninstall <pkg>` for each unused dep.
- D4: `npm install <pkg>` for each missing dep.
- D5: `npm install` to regenerate lockfile, commit it.
- D6: `npm dedupe` then verify tests pass.
LOCK_DATE=$(git log -1 --format=%ct -- package-lock.json 2>/dev/null || echo 0) PKG_DATE=$(git log -1 --format=%ct -- package.json 2>/dev/null || echo 0) if [ "$PKG_DATE" -gt "$LOCK_DATE" ]; then echo "⚠️ package.json修改时间晚于lockfile — 请运行npm install" fi

**修复方案：**

- D1：运行`npm audit fix`应用兼容修复；使用`npm audit fix --force`应用可能存在破坏性的修复（需仔细审查变更）。对于顽固漏洞：检查漏洞是否可被触发，或在`package.json`的`overrides`中覆盖依赖版本。
- D2：运行`npm update`更新小版本/补丁；运行`npm install <pkg>@latest`更新大版本（需查看变更日志）。
- D3：对每个未使用的依赖项运行`npm uninstall <pkg>`。
- D4：对每个缺失的依赖项运行`npm install <pkg>`。
- D5：运行`npm install`重新生成锁文件并提交。
- D6：运行`npm dedupe`后验证测试是否通过。

Python (uv / pip)

Python (uv / pip)

#CheckCommandSeverity
D1Known vulnerabilities
pip-audit --format=json
🔴 Fix Now
D2Outdated dependencies
uv pip list --outdated
or 
pip list --outdated --format=json
🟡 Fix Soon
D3Unused dependencies
deptry . --json
(if available)		🟡 Fix Soon
D5Lockfile freshnessCompare 
uv.lock
vs 
pyproject.toml
timestamps		🟡 Fix Soon
How to fix:
  • D1: 
    uv pip install --upgrade <pkg>
    for each vulnerable package. Check advisories for minimum safe version.
  • D2: 
    uv pip install --upgrade <pkg>
    per package, or 
    uv lock --upgrade
    for all.
  • D3: Remove from 
    [project.dependencies]
    in 
    pyproject.toml
    , then 
    uv sync
    .
  • D5: 
    uv lock && uv sync
    .
编号检查项命令严重程度
D1已知漏洞
pip-audit --format=json
🔴 立即修复
D2过时依赖项
uv pip list --outdated
或 
pip list --outdated --format=json
🟡 尽快修复
D3未使用依赖项
deptry . --json
（若已安装）		🟡 尽快修复
D5锁文件新鲜度对比
uv.lock
与
pyproject.toml
的时间戳		🟡 尽快修复
修复方案：
  • D1：对每个存在漏洞的包运行
    uv pip install --upgrade <pkg>
    。查看漏洞公告确认最低安全版本。
  • D2：对单个包运行
    uv pip install --upgrade <pkg>
    ，或运行
    uv lock --upgrade
    更新所有依赖。
  • D3：从
    pyproject.toml
    的
    [project.dependencies]
    中移除未使用的依赖，然后运行
    uv sync
    。
  • D5：运行
    uv lock && uv sync
    。

Go

Go

#CheckCommandSeverity
D1Known vulnerabilities
govulncheck ./...
🔴 Fix Now
D2Outdated dependencies
go list -m -u all
🟡 Fix Soon
D3Unused dependencies
go mod tidy -v
(reports removed)		🟡 Fix Soon
How to fix:
  • D1: 
    go get <module>@latest
    for vulnerable deps, then 
    go mod tidy
    .
  • D2: 
    go get -u ./...
    for all, or 
    go get <module>@latest
    selectively.
  • D3: 
    go mod tidy
    removes unused; commit 
    go.mod
    and 
    go.sum
    .
编号检查项命令严重程度
D1已知漏洞
govulncheck ./...
🔴 立即修复
D2过时依赖项
go list -m -u all
🟡 尽快修复
D3未使用依赖项
go mod tidy -v
（会报告移除的依赖）		🟡 尽快修复
修复方案：
  • D1：对存在漏洞的依赖运行
    go get <module>@latest
    ，然后运行
    go mod tidy
    。
  • D2：运行
    go get -u ./...
    更新所有依赖，或选择性运行
    go get <module>@latest
    。
  • D3：运行
    go mod tidy
    移除未使用的依赖，提交
    go.mod
    和
    go.sum
    。

Step 2: Git Hygiene

步骤2：Git仓库维护

#CheckCommandSeverity
G1Stale local branches (merged)
git branch --merged main | grep -v '^\*|main|develop'
🟡 Fix Soon
G2Stale remote branches (merged)
git branch -r --merged origin/main | grep -v 'HEAD|main|develop'
🟡 Fix Soon
G3Large files in repoSee below🟡 Fix Soon (🔴 if >10MB)
G4
.gitignore
completeness		See below🟡 Fix Soon
G5Untracked files that should be ignored
git status --porcelain | grep '^??'
— look for build artifacts, IDE files, env files		ℹ️ Info
G6Uncommitted changes
git status --porcelain
ℹ️ Info
G3 — Large files check:
bash
undefined
编号检查项命令严重程度
G1已合并的本地 stale 分支
git branch --merged main | grep -v '^\*|main|develop'
🟡 尽快修复
G2已合并的远程 stale 分支
git branch -r --merged origin/main | grep -v 'HEAD|main|develop'
🟡 尽快修复
G3仓库中的大文件见下方说明🟡 尽快修复（🔴 若文件>10MB）
G4
.gitignore
完整性		见下方说明🟡 尽快修复
G5应被忽略但未被追踪的文件
git status --porcelain | grep '^??'
— 查找构建产物、IDE配置文件、环境文件		ℹ️ 信息提示
G6未提交的变更
git status --porcelain
ℹ️ 信息提示
G3 — 大文件检查：
bash
undefined

Top 10 largest tracked files

查看前10个最大的已追踪文件

git ls-files -z | xargs -0 -I{} git log --diff-filter=A --format='%H' -1 -- '{}' | head -20
git ls-files -z | xargs -0 -I{} git log --diff-filter=A --format='%H' -1 -- '{}' | head -20

Simpler: just check current tree

简化版：仅检查当前工作树

git ls-files -z | xargs -0 du -sh 2>/dev/null | sort -rh | head -10

**G4 — .gitignore completeness:**

Must include (per stack):

- **Universal**: `.env`, `.env.*`, `*.local`, `.DS_Store`, `Thumbs.db`, `*.swp`, `.idea/`, `.vscode/` (or be deliberate about tracking it)
- **Node**: `node_modules/`, `dist/`, `build/`, `coverage/`, `.turbo/`, `.next/`
- **Python**: `__pycache__/`, `*.pyc`, `.venv/`, `venv/`, `.mypy_cache/`, `.pytest_cache/`, `*.egg-info/`
- **Go**: binary name (check `go build -o`), `vendor/` (if not vendoring)

**How to fix:**

- G1: `git branch -d <branch>` for each merged local branch.
- G2: `git push origin --delete <branch>` for each merged remote branch. Be careful — confirm with team.
- G3: For files that shouldn't be tracked: add to `.gitignore`, `git rm --cached <file>`. For files already in history: `git filter-repo` or BFG Repo-Cleaner (destructive — confirm first).
- G4: Add missing patterns to `.gitignore`. Use a generator like [gitignore.io](https://gitignore.io) as a starting point.
- G5: Either add to `.gitignore` or `git add` if they should be tracked.

---
git ls-files -z | xargs -0 du -sh 2>/dev/null | sort -rh | head -10

**G4 — .gitignore完整性：**

需包含以下内容（按技术栈分类）：

- **通用**：`.env`, `.env.*`, `*.local`, `.DS_Store`, `Thumbs.db`, `*.swp`, `.idea/`, `.vscode/`（若刻意追踪则除外）
- **Node**：`node_modules/`, `dist/`, `build/`, `coverage/`, `.turbo/`, `.next/`
- **Python**：`__pycache__/`, `*.pyc`, `.venv/`, `venv/`, `.mypy_cache/`, `.pytest_cache/`, `*.egg-info/`
- **Go**：二进制文件名（查看`go build -o`配置）、`vendor/`（若未启用依赖 vendoring）

**修复方案：**

- G1：对每个已合并的本地分支运行`git branch -d <branch>`。
- G2：对每个已合并的远程分支运行`git push origin --delete <branch>`。操作前需谨慎——请与团队确认。
- G3：对于不应被追踪的文件：添加到`.gitignore`，运行`git rm --cached <file>`。对于已存在于历史中的大文件：使用`git filter-repo`或BFG Repo-Cleaner（操作具有破坏性——需先确认）。
- G4：向`.gitignore`添加缺失的规则。可使用[gitignore.io](https://gitignore.io)作为生成起点。
- G5：要么添加到`.gitignore`，要么运行`git add`将其纳入追踪（若属于应追踪文件）。

---

Step 3: CI/CD Health

步骤3：CI/CD健康检查

Skip if no CI configuration found.
#CheckCommandSeverity
C1Workflow files exist
ls .github/workflows/*.yml 2>/dev/null
ℹ️ Info
C2Actions pinned by SHA
grep -rE 'uses: [^@]+@v[0-9]' .github/workflows/
— should return nothing		🟡 Fix Soon
C3Least-privilege permissionsScan for 
permissions:
blocks; flag 
write-all
or missing job-level perms		🟡 Fix Soon
C4No secret leaks in workflowsCheck for 
echo ${{ secrets.* }}
, secret in 
$GITHUB_OUTPUT
/
$GITHUB_ENV
🔴 Fix Now
C5Deprecated actionsCheck for known deprecated: 
actions/create-release@v1
, 
set-output
commands, 
::set-env
🟡 Fix Soon
C6Node/Python version matches projectCompare workflow matrix with 
engines
, 
.nvmrc
, 
pyproject.toml [requires-python]
🟡 Fix Soon
How to fix:
  • C2: Replace 
    uses: actions/checkout@v4
    with 
    uses: actions/checkout@<full-sha>
    . Find SHA: 
    gh api repos/actions/checkout/git/ref/tags/v4 --jq .object.sha
    or check the releases page.
  • C3: Add explicit 
    permissions:
    at job level. Start with 
    contents: read
    and add only what's needed.
  • C4: Remove secret interpolation. Use 
    environment:
    blocks or write to files with masking.
  • C5: Replace deprecated actions with current equivalents. 
    set-output
    → 
    $GITHUB_OUTPUT
    file.
  • C6: Align versions. Use 
    .nvmrc
    or 
    engines
    as the source of truth.
若未发现CI配置文件则跳过此步骤。
编号检查项命令严重程度
C1工作流文件是否存在
ls .github/workflows/*.yml 2>/dev/null
ℹ️ 信息提示
C2Actions是否通过SHA固定版本
grep -rE 'uses: [^@]+@v[0-9]' .github/workflows/
— 应无结果返回		🟡 尽快修复
C3权限是否遵循最小权限原则扫描
permissions:
块；标记
write-all
或缺失作业级权限的情况		🟡 尽快修复
C4工作流中是否存在密钥泄露检查是否有
echo ${{ secrets.* }}
、密钥写入
$GITHUB_OUTPUT
/
$GITHUB_ENV
的情况		🔴 立即修复
C5是否存在已弃用的Actions检查已知弃用项：
actions/create-release@v1
、
set-output
命令、
::set-env
🟡 尽快修复
C6Node/Python版本是否与项目匹配对比工作流矩阵与
engines
、
.nvmrc
、
pyproject.toml [requires-python]
的配置		🟡 尽快修复
修复方案：
  • C2：将
    uses: actions/checkout@v4
    替换为
    uses: actions/checkout@<完整SHA>
    。获取SHA：运行
    gh api repos/actions/checkout/git/ref/tags/v4 --jq .object.sha
    或查看Releases页面。
  • C3：在作业级别添加明确的
    permissions:
    配置。从
    contents: read
    开始，仅添加必要的权限。
  • C4：移除密钥插值。使用
    environment:
    块或写入带掩码的文件。
  • C5：将已弃用的Actions替换为当前等效项。
    set-output
    → 
    $GITHUB_OUTPUT
    文件。
  • C6：对齐版本。推荐使用
    .nvmrc
    或
    engines
    作为版本唯一可信源。

Step 4: Code Quality Drift

步骤4：代码质量漂移检查

#CheckCommandSeverity
Q1TODO/FIXME/HACK count
git grep -ciE '(TODO|FIXME|HACK)' -- '*.ts' '*.js' '*.py' '*.go' ':!node_modules' ':!vendor' ':!.venv'
ℹ️ Info (🟡 if >20)
Q2
console.log
in src (JS/TS)
git grep -c 'console\.log' -- 'src/**/*.ts' 'src/**/*.js' ':!*.test.*' ':!*.spec.*'
🟡 Fix Soon
Q3Disabled/skipped tests
git grep -cE '(it\.skip|test\.skip|describe\.skip|xit|xdescribe|@pytest\.mark\.skip|t\.Skip)' -- '*.test.*' '*.spec.*' '*_test.*' '*_test.go'
🟡 Fix Soon
Q4Lint passes
npm run lint
/ 
ruff check .
/ 
golangci-lint run
🟡 Fix Soon
Q5Tests pass
npm test
/ 
pytest
/ 
go test ./...
🔴 Fix Now
Q6Build succeeds
npm run build
/ 
uv build
/ 
go build ./...
🔴 Fix Now
Q7Type errors (TS)
npx tsc --noEmit
🟡 Fix Soon
Q8Dead exports (TS)
npx ts-prune 2>/dev/null | grep -v '(used in module)'
ℹ️ Info
How to fix:
  • Q1: Triage each TODO — either do it, create an issue/task for it, or remove it if obsolete.
  • Q2: Replace with a proper logger, or remove debug logging. 
    grep -rn 'console.log' src/
    to find them.
  • Q3: Either fix the underlying issue and un-skip, or delete the test if the feature was removed.
  • Q4–Q7: Fix the errors. Run the tool, address each issue.
  • Q8: Remove unused exports, or add 
    // ts-prune-ignore-next
    if they're part of the public API.
编号检查项命令严重程度
Q1TODO/FIXME/HACK数量
git grep -ciE '(TODO|FIXME|HACK)' -- '*.ts' '*.js' '*.py' '*.go' ':!node_modules' ':!vendor' ':!.venv'
ℹ️ 信息提示（🟡 若数量>20）
Q2源码中存在
console.log
（JS/TS）
git grep -c 'console\.log' -- 'src/**/*.ts' 'src/**/*.js' ':!*.test.*' ':!*.spec.*'
🟡 尽快修复
Q3已禁用/跳过的测试用例
git grep -cE '(it\.skip|test\.skip|describe\.skip|xit|xdescribe|@pytest\.mark\.skip|t\.Skip)' -- '*.test.*' '*.spec.*' '*_test.*' '*_test.go'
🟡 尽快修复
Q4代码检查是否通过
npm run lint
/ 
ruff check .
/ 
golangci-lint run
🟡 尽快修复
Q5测试是否通过
npm test
/ 
pytest
/ 
go test ./...
🔴 立即修复
Q6构建是否成功
npm run build
/ 
uv build
/ 
go build ./...
🔴 立即修复
Q7TypeScript是否存在类型错误
npx tsc --noEmit
🟡 尽快修复
Q8是否存在未使用的导出（TS）
npx ts-prune 2>/dev/null | grep -v '(used in module)'
ℹ️ 信息提示
修复方案：
  • Q1：逐个梳理TODO项——要么立即处理，要么创建议题/任务，若已过时则直接删除。
  • Q2：替换为正式日志工具，或移除调试日志。运行
    grep -rn 'console.log' src/
    定位所有实例。
  • Q3：要么修复底层问题并重新启用测试，要么删除测试用例（若对应功能已移除）。
  • Q4–Q7：修复所有错误。运行对应工具，逐个解决问题。
  • Q8：移除未使用的导出，若属于公共API则添加
    // ts-prune-ignore-next
    注释。

Step 5: Documentation Freshness

步骤5：文档新鲜度检查

#CheckCommandSeverity
F1README.md existsFile check🔴 Fix Now
F2README freshness vs. sourceCompare 
git log -1 --format=%cr -- README.md
vs 
git log -1 --format=%cr -- src/
🟡 if src is >30 days newer
F3CHANGELOG existsFile check🟡 Fix Soon (for published packages)
F4Broken internal linksSee below🟡 Fix Soon
F5LICENSE file presentFile check🔴 Fix Now
F6LICENSE matches package metadataCompare LICENSE text with 
package.json
license
/ 
pyproject.toml
license
🟡 Fix Soon
F7AGENTS.md references valid pathsIf 
.pi/AGENTS.md
exists, check that referenced files/dirs exist		🟡 Fix Soon
F4 — Broken link check:
bash
undefined
编号检查项命令严重程度
F1README.md是否存在文件检查🔴 立即修复
F2README与源码的新鲜度对比对比
git log -1 --format=%cr -- README.md
与
git log -1 --format=%cr -- src/
的结果		🟡 若源码更新时间比README晚30天以上
F3CHANGELOG是否存在文件检查🟡 尽快修复（针对已发布的包）
F4是否存在内部链接失效见下方说明🟡 尽快修复
F5LICENSE文件是否存在文件检查🔴 立即修复
F6LICENSE是否与包元数据匹配对比LICENSE文本与
package.json
的
license
字段 / 
pyproject.toml
的
license
字段		🟡 尽快修复
F7AGENTS.md是否引用有效路径若
.pi/AGENTS.md
存在，检查其中引用的文件/目录是否存在		🟡 尽快修复
F4 — 失效链接检查：
bash
undefined

Find markdown links and verify targets exist

查找Markdown链接并验证目标是否存在

grep -roE '[([^]]+)](([^)]+))' .md docs/**/.md 2>/dev/null |
grep -v 'http' |
while IFS= read -r line; do # Extract path from markdown link path=$(echo "$line" | sed 's/.](([^)]))./\1/' | sed 's/#.//') if [ -n "$path" ] && [ ! -e "$path" ]; then echo "BROKEN: $line" fi done

**How to fix:**

- F1: Write a README with: what it does, how to install, how to use, prerequisites, license.
- F2: Review README against current code — update examples, API docs, feature lists.
- F3: Add a CHANGELOG.md. Consider `@changesets/cli` for automated generation (see `pre-release` skill).
- F4: Update or remove broken links.
- F5: Add a LICENSE file. Use [choosealicense.com](https://choosealicense.com) if unsure.
- F6: Make LICENSE file and metadata agree.
- F7: Update AGENTS.md to reflect current project structure.

---
grep -roE '[([^]]+)](([^)]+))' .md docs/**/.md 2>/dev/null |
grep -v 'http' |
while IFS= read -r line; do # 从Markdown链接中提取路径 path=$(echo "$line" | sed 's/.](([^)]))./\1/' | sed 's/#.//') if [ -n "$path" ] && [ ! -e "$path" ]; then echo "失效链接: $line" fi done

**修复方案：**

- F1：编写README，内容应包含：功能介绍、安装方法、使用方法、前置依赖、许可证。
- F2：对照当前代码审查README——更新示例、API文档、功能列表。
- F3：添加CHANGELOG.md。可考虑使用`@changesets/cli`自动生成（参考`pre-release`技能）。
- F4：更新或移除失效链接。
- F5：添加LICENSE文件。若不确定选择哪种许可证，可使用[choosealicense.com](https://choosealicense.com)。
- F6：确保LICENSE文件与元数据中的许可证信息一致。
- F7：更新AGENTS.md以反映当前项目结构。

---

Step 6: Configuration Consistency

步骤6：配置一致性检查

#CheckHowSeverity
X1EditorConfig present
.editorconfig
exists		ℹ️ Info
X2Strict mode (TS)
tsconfig.json
→ 
"strict": true
🟡 Fix Soon
X3Formatter configured
.prettierrc
/ 
ruff.toml
/ 
gofmt
(built-in)		🟡 Fix Soon
X4Linter configured
.eslintrc*
or 
eslint.config.*
/ 
ruff.toml
/ 
golangci-lint
config		🟡 Fix Soon
X5Engine constraints match CI
package.json
engines
vs CI matrix; 
pyproject.toml
requires-python
vs CI		🟡 Fix Soon
X6
.nvmrc
/ 
.python-version
matches		Compare with 
engines
/ 
requires-python
/ CI config		ℹ️ Info
How to fix:
  • X1: Add 
    .editorconfig
    . Minimal: 
    root = true
    , 
    [*]
    block with 
    indent_style
    , 
    indent_size
    , 
    end_of_line
    , 
    insert_final_newline
    .
  • X2: Set 
    "strict": true
    in 
    tsconfig.json
    . Fix resulting type errors (usually worth it).
  • X3–X4: Add config files. Use the project's existing style as a baseline.
  • X5–X6: Pick one source of truth (recommend 
    engines
    / 
    requires-python
    ) and align everything else.
编号检查项检查方式严重程度
X1是否存在EditorConfig
.editorconfig
文件是否存在		ℹ️ 信息提示
X2TypeScript是否启用严格模式
tsconfig.json
中是否设置
"strict": true
🟡 尽快修复
X3是否配置格式化工具是否存在
.prettierrc
/ 
ruff.toml
/ 
gofmt
（Go内置）		🟡 尽快修复
X4是否配置代码检查工具是否存在
.eslintrc*
或
eslint.config.*
/ 
ruff.toml
/ 
golangci-lint
配置文件		🟡 尽快修复
X5引擎约束是否与CI匹配
package.json
的
engines
字段与CI矩阵对比；
pyproject.toml
的
requires-python
与CI对比		🟡 尽快修复
X6
.nvmrc
/ 
.python-version
是否与配置匹配		与
engines
/ 
requires-python
/ CI配置对比		ℹ️ 信息提示
修复方案：
  • X1：添加
    .editorconfig
    。最小配置：
    root = true
    ，
    [*]
    块包含
    indent_style
    、
    indent_size
    、
    end_of_line
    、
    insert_final_newline
    。
  • X2：在
    tsconfig.json
    中设置
    "strict": true
    。修复由此产生的类型错误（通常值得投入）。
  • X3–X4：添加配置文件。以项目现有代码风格为基准。
  • X5–X6：选定一个可信源（推荐
    engines
    / 
    requires-python
    ），并对齐所有其他配置。

Step 7: Security Posture

步骤7：安全态势检查

Lightweight security checks for ongoing hygiene. For the full pre-release security audit (gitleaks, trufflehog, workflow audit), use the 
pre-release
skill.
#CheckCommandSeverity
S1No tracked 
.env
or 
.local
files
git ls-files '*.env' '*.env.*' '*.local' '*.local.*' '.env' '.env.local'
🔴 Fix Now
S2
.env.example
exists (if 
.env
in 
.gitignore
)		File check🟡 Fix Soon
S3No hardcoded secrets in source
git grep -iE '(api[_-]?key|secret|password|token)\s*[:=]\s*["\x27][^"\x27]{8,}' -- ':!*.lock' ':!node_modules' ':!*.example' ':!*.sample'
🔴 Fix Now
S4Secrets scanning config present
.gitleaks.toml
or pre-commit hooks		ℹ️ Info
S5No broad file permissionsCheck for 
chmod 777
or 
0777
in scripts		🔴 Fix Now
How to fix:
  • S1: 
    git rm --cached <file>
    , add to 
    .gitignore
    , commit. If the file contained real secrets, rotate them immediately — they're in git history.
  • S2: Create 
    .env.example
    with placeholder values (
    <REPLACE_ME>
    ) for every var in 
    .env
    .
  • S3: Move secrets to env vars or a secrets manager. Replace in code with 
    process.env.VAR
    / 
    os.environ["VAR"]
    .
  • S4: Add 
    .gitleaks.toml
    (even a minimal one enables CI scanning). Or add 
    gitleaks
    to pre-commit hooks.
  • S5: Use least-privilege permissions (
    644
    for files, 
    755
    for executables).
针对日常维护的轻量级安全检查。若需完整的预发布安全审计（gitleaks、trufflehog、工作流审计），请使用
pre-release
技能。
编号检查项命令严重程度
S1是否存在被追踪的
.env
或
.local
文件
git ls-files '*.env' '*.env.*' '*.local' '*.local.*' '.env' '.env.local'
🔴 立即修复
S2若
.env
在
.gitignore
中，是否存在
.env.example
文件检查🟡 尽快修复
S3源码中是否存在硬编码密钥
git grep -iE '(api[_-]?key|secret|password|token)\s*[:=]\s*["\x27][^"\x27]{8,}' -- ':!*.lock' ':!node_modules' ':!*.example' ':!*.sample'
🔴 立即修复
S4是否存在密钥扫描配置是否存在
.gitleaks.toml
或预提交钩子		ℹ️ 信息提示
S5是否存在过宽的文件权限检查脚本中是否存在
chmod 777
或
0777
🔴 立即修复
修复方案：
  • S1：运行
    git rm --cached <file>
    ，添加到
    .gitignore
    ，提交变更。若文件包含真实密钥，需立即轮换——因为它们已存在于Git历史中。
  • S2：创建
    .env.example
    ，为
    .env
    中的每个变量添加占位值（
    <REPLACE_ME>
    ）。
  • S3：将密钥迁移到环境变量或密钥管理系统。在代码中替换为
    process.env.VAR
    / 
    os.environ["VAR"]
    。
  • S4：添加
    .gitleaks.toml
    （即使是最小配置也能启用CI扫描）。或在预提交钩子中添加
    gitleaks
    。
  • S5：使用最小权限（文件为
    644
    ，可执行文件为
    755
    ）。

Step 8: Project Metadata

步骤8：项目元数据检查

#CheckHowSeverity
M1Required package fields
name
, 
version
, 
description
, 
license
in 
package.json
/ 
pyproject.toml
🟡 Fix Soon
M2Repository URL set
repository
field in package metadata		🟡 Fix Soon
M3Keywords present
keywords
array		ℹ️ Info
M4
FUNDING.yml
(public repos)
.github/FUNDING.yml
exists		ℹ️ Info
M5Pi package complianceIf ships skills/extensions: 
pi-package
keyword, 
pi
manifest, 
files
includes skill dirs		🟡 Fix Soon (if applicable)
How to fix:
  • M1–M3: Add the missing fields to 
    package.json
    or 
    pyproject.toml
    .
  • M4: Create 
    .github/FUNDING.yml
    with 
    github: <username>
    .
  • M5: See pi package docs for required fields.
编号检查项检查方式严重程度
M1包必填字段是否完整
package.json
/ 
pyproject.toml
中是否包含
name
、
version
、
description
、
license
🟡 尽快修复
M2是否设置仓库URL包元数据中是否存在
repository
字段		🟡 尽快修复
M3是否存在关键词是否存在
keywords
数组		ℹ️ 信息提示
M4公共仓库是否存在
FUNDING.yml
.github/FUNDING.yml
是否存在		ℹ️ 信息提示
M5是否符合Pi包规范若包含技能/扩展：是否存在
pi-package
关键词、
pi
清单、
files
字段包含技能目录		🟡 尽快修复（若适用）
修复方案：
  • M1–M3：向
    package.json
    或
    pyproject.toml
    添加缺失字段。
  • M4：创建
    .github/FUNDING.yml
    ，添加
    github: <username>
    。
  • M5：参考Pi包文档补充必填字段。

Baseline Tracking

基线跟踪

Save a baseline after each run to detect drift over time. Store at 
.pi/hygiene-baseline.json
:
json
{
  "timestamp": "2026-02-14T23:00:00Z",
  "stack": ["node"],
  "scores": {
    "dependencies": { "status": "healthy", "vulns": 0, "outdated": 3, "unused": 0 },
    "git": { "status": "healthy", "stale_branches": 0, "large_files": 0 },
    "ci": { "status": "warning", "unpinned_actions": 2, "permission_issues": 0 },
    "quality": { "status": "healthy", "todos": 5, "skipped_tests": 0, "lint_clean": true },
    "docs": { "status": "warning", "readme_stale_days": 45, "broken_links": 1 },
    "config": { "status": "healthy", "strict_ts": true, "formatter": true, "linter": true },
    "security": { "status": "healthy", "tracked_env": 0, "hardcoded_secrets": 0 },
    "metadata": { "status": "healthy", "complete": true }
  },
  "overall": "7/10"
}
On subsequent runs, compare with baseline and flag regressions:
text
📉 Dependencies: 0 → 3 vulnerabilities (regression since last check)
📈 Quality: 15 → 5 TODOs (improvement!)
→  CI: unchanged — 2 unpinned actions remain
When the user approves the report, offer to update the baseline.
每次运行后保存基线，以检测随时间的代码漂移。将基线存储在
.pi/hygiene-baseline.json
：
json
{
  "timestamp": "2026-02-14T23:00:00Z",
  "stack": ["node"],
  "scores": {
    "dependencies": { "status": "healthy", "vulns": 0, "outdated": 3, "unused": 0 },
    "git": { "status": "healthy", "stale_branches": 0, "large_files": 0 },
    "ci": { "status": "warning", "unpinned_actions": 2, "permission_issues": 0 },
    "quality": { "status": "healthy", "todos": 5, "skipped_tests": 0, "lint_clean": true },
    "docs": { "status": "warning", "readme_stale_days": 45, "broken_links": 1 },
    "config": { "status": "healthy", "strict_ts": true, "formatter": true, "linter": true },
    "security": { "status": "healthy", "tracked_env": 0, "hardcoded_secrets": 0 },
    "metadata": { "status": "healthy", "complete": true }
  },
  "overall": "7/10"
}
后续运行时，与基线对比并标记退化情况：
text
📉 依赖项：0 → 3个漏洞（自上次检查后出现退化）
📈 代码质量：15 → 5个TODO项（有所改善！）
→  CI：无变化 — 仍有2个未固定版本的Actions
当用户确认报告后，可提供更新基线的选项。

Report Format

报告格式

Present the final report as a health scorecard:
markdown
undefined
最终报告以健康评分卡形式呈现：
markdown
undefined

Repo Health: <project-name>

仓库健康状态: <项目名称>

Score: 7/10 — GOOD

评分: 7/10 — 良好

Stack: Node.js + TypeScript

技术栈: Node.js + TypeScript

Last check: 2026-01-15 (30 days ago) | Baseline: 6/10 📈

上次检查: 2026-01-15（30天前） | 基线评分: 6/10 📈

🔴 Fix Now (2)

🔴 立即修复（2项）

#CategoryIssueFix
S1Security
.env.local
tracked in git
git rm --cached .env.local
D1Deps2 high-severity npm audit findings
npm audit fix
编号分类问题修复方案
S1安全
.env.local
被Git追踪
git rm --cached .env.local
D1依赖项npm audit发现2个高危漏洞
npm audit fix

🟡 Fix Soon (4)

🟡 尽快修复（4项）

#CategoryIssueFix
D2Deps8 outdated packages (2 major)
npm outdated
→ upgrade
C2CI3 actions not pinned by SHAPin to commit SHA
F2DocsREADME 45 days behind sourceReview and update
Q3Quality2 skipped testsFix or remove
编号分类问题修复方案
D2依赖项8个过时包（2个大版本更新）运行
npm outdated
→ 升级对应包
C2CI/CD3个Actions未通过SHA固定版本固定到提交SHA
F2文档README比源码晚更新45天审查并更新
Q3代码质量2个被跳过的测试用例修复或删除

🟢 Healthy (12)

🟢 状态健康（12项）

  • ✅ Dependencies: no unused, no phantom, lockfile fresh
  • ✅ Git: clean tree, no stale branches, no large files
  • ✅ Code: lint clean, build passes, tests pass, strict TS
  • ✅ Config: EditorConfig, Prettier, ESLint all configured
  • ✅ Security: no tracked secrets, .env.example present
  • ✅ Metadata: all fields present, license matches
  • ✅ 依赖项：无未使用依赖、无幽灵依赖、锁文件新鲜
  • ✅ Git：工作树干净、无stale分支、无大文件
  • ✅ 代码：代码检查通过、构建成功、测试通过、TypeScript严格模式已启用
  • ✅ 配置：已配置EditorConfig、Prettier、ESLint
  • ✅ 安全：无被追踪的密钥、已存在.env.example
  • ✅ 元数据：所有字段完整、许可证信息一致

📊 Trends (vs. baseline 2026-01-15)

📊 趋势对比（与2026-01-15基线对比）

CategoryThenNowTrend
Vulnerabilities02📉
Outdated deps58📉
TODOs158📈
Skipped tests02📉
分类上次当前趋势
漏洞数量02📉
过时依赖数量58📉
TODO数量158📈
被跳过的测试数量02📉

Recommendations

建议

  1. Immediate: Fix the 2 security/vulnerability items above
  2. This week: Pin CI actions and update stale README
  3. Ongoing: Address skipped tests and outdated deps in next sprint
Use your project's task tracking to schedule these items.

---
  1. 立即处理：修复上述2个安全/漏洞问题
  2. 本周内：固定CI Actions版本并更新过时的README
  3. 持续跟进：在下一个迭代中处理被跳过的测试和过时依赖
使用项目的任务跟踪系统安排这些事项。

---

Scoring

评分规则

Calculate the score from check results:
ResultPoints deducted
Each 🔴 Fix Now−1.5
Each 🟡 Fix Soon−0.5
ℹ️ Info0
Start at 10, apply deductions, floor at 0. Round to nearest integer.
ScoreLabel
9–10🟢 EXCELLENT
7–8🟢 GOOD
5–6🟡 FAIR
3–4🟠 NEEDS WORK
0–2🔴 POOR
根据检查结果计算评分：
结果扣分
每个🔴 立即修复项−1.5
每个🟡 尽快修复项−0.5
ℹ️ 信息提示项0
初始分为10分，应用扣分后，最低为0分。结果四舍五入到最近整数。
评分标签
9–10🟢 优秀
7–8🟢 良好
5–6🟡 一般
3–4🟠 需要改进
0–2🔴 较差

Auto-Fix Offers

自动修复建议

After presenting the report, offer to fix issues that are safe and mechanical. Always present what will be done and get confirmation before executing.
呈现报告后，可提供安全且机械性的问题修复选项。在执行前必须明确告知用户将执行的操作并获得确认。

Safe to offer (low risk, reversible)

可安全提供的修复（低风险、可回滚）

  • Delete merged local branches (
    git branch -d
    )
  • Run 
    npm audit fix
    (compatible fixes only, not 
    --force
    )
  • Run 
    npm dedupe
    / 
    go mod tidy
  • Add missing 
    .gitignore
    patterns
  • Add 
    .editorconfig
    from template
  • Remove 
    console.log
    from source files
  • Create 
    .env.example
    from 
    .env
    (with values replaced by 
    <REPLACE_ME>
    )
  • Add missing 
    package.json
    fields (description, repository, keywords)
  • Create 
    .github/FUNDING.yml
  • 删除已合并的本地分支（
    git branch -d
    ）
  • 运行
    npm audit fix
    （仅应用兼容修复，不使用
    --force
    ）
  • 运行
    npm dedupe
    / 
    go mod tidy
  • 添加缺失的
    .gitignore
    规则
  • 从模板添加
    .editorconfig
  • 移除源码中的
    console.log
  • 从
    .env
    生成
    .env.example
    （将值替换为
    <REPLACE_ME>
    ）
  • 添加缺失的
    package.json
    字段（描述、仓库、关键词）
  • 创建
    .github/FUNDING.yml

Offer with warning (confirm carefully)

需谨慎提供的修复（需仔细确认）

  • Delete merged remote branches (
    git push origin --delete
    )
  • Run 
    npm audit fix --force
    (may have breaking changes)
  • Major dependency upgrades
  • Enable TypeScript strict mode (may produce many errors)
  • Update CI action pinning (must verify correct SHAs)
  • 删除已合并的远程分支（
    git push origin --delete
    ）
  • 运行
    npm audit fix --force
    （可能存在破坏性变更）
  • 大版本依赖升级
  • 启用TypeScript严格模式（可能产生大量错误）
  • 更新CI Action版本固定（必须验证SHA正确性）

Never auto-fix (explain, let user decide)

禁止自动修复（需说明情况，由用户决定）

  • Removing tracked 
    .env
    files (may need secret rotation)
  • Rewriting git history (BFG / filter-repo)
  • Changing license files
  • Modifying CI permissions model
  • Removing hardcoded secrets (need to determine replacement strategy)
  • 移除被追踪的
    .env
    文件（可能需要轮换密钥）
  • 重写Git历史（BFG / filter-repo）
  • 修改许可证文件
  • 修改CI权限模型
  • 移除硬编码密钥（需确定替换策略）

Tips

小贴士

  • Run early, run often. A monthly cadence catches drift before it compounds.
  • Don't try to fix everything at once. Focus on 🔴 items first, batch 🟡 items into a maintenance sprint.
  • Baseline tracking is your friend. Even if the score isn't perfect, trending upward means you're winning.
  • Pair with pre-release. Run 
    repo-hygiene
    for ongoing health, 
    pre-release
    when you're ready to ship. They complement each other — hygiene keeps the baseline high so pre-release has fewer surprises.
  • New repos start clean. Run this right after 
    git init
    to establish a perfect baseline. It's easier to maintain 10/10 than to recover from 4/10.
  • 尽早运行、定期运行。每月一次的检查可在问题恶化前及时发现代码漂移。
  • 不要试图一次性修复所有问题。优先处理🔴 项，将🟡 项批量安排到维护迭代中。
  • 基线跟踪很重要。即使评分不完美，只要呈上升趋势就说明在进步。
  • 与pre-release技能配合使用。使用
    repo-hygiene
    进行日常健康维护，使用
    pre-release
    进行发布前检查。二者互补——日常维护可保持基线水平，让预发布检查更少出现意外。
  • 新仓库从干净状态开始。在
    git init
    后立即运行此检查，建立完美基线。维持10分比从4分恢复更容易。