القائمة
文档园丁技能，定期扫描识别过时或废弃文档，保持知识库新鲜度。当用户需要文档一致性检查、文档更新或清理时自动触发。支持中文触发：文档清理、文档一致性、更新文档。
يُحدَّد Prompt الذي يراجع المصدر أولًا بشكل افتراضي. يمكنك التبديل إلى أمر مباشر أو تنزيل نسخة محلية.
اقرأ SKILL.md وأي ملفات مرافقة يعرضها SkillsMP قبل أن تقرر التثبيت.
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
يتجاوز الأمر المباشر Prompt المخصّص للمراجعة. افحص المصدر قبل تشغيله.
npx skills add https://github.com/wonderslife/pdd-skills-v3 --skill pdd-doc-gardenerيبقى الأمر في سطر واحد. مرّر أفقيًا لمراجعته كاملًا قبل النسخ.
تفضّل نسخة محلية؟ نزّل الملفات المتاحة حاليًا لدى SkillsMP.
استنادا إلى تصنيف SOC المهني
عرض SKILL.md
| name | pdd-doc-gardener |
| description | 文档园丁技能，定期扫描识别过时或废弃文档，保持知识库新鲜度。当用户需要文档一致性检查、文档更新或清理时自动触发。支持中文触发：文档清理、文档一致性、更新文档。 |
| license | MIT |
| compatibility | 需要文档目录 (docs/) |
| metadata | {"author":"neuqik@hotmail.com","version":"1.0","parent":"pdd-entropy-reduction"} |
"文档即代码，保持同步。文档过时即视为技术债务。" —— PDD 黄金原则
定期扫描代码仓库中的 docs/ 目录,识别不再反映真实代码行为的过时或废弃文档。
"Documentation is code — keep it in sync. Outdated documentation is technical debt." —— PDD Golden Principle
Periodically scan the docs/ directory in the code repository to identify outdated or deprecated documents that no longer reflect actual code behavior.
解析文档中的代码引用(文件路径/函数名/API端点) → 检查代码是否存在及行为是否一致
示例: 文档描述"API /api/users返回用户列表" | 实际代码返回用户详情(含订单) → 检测结果:文档过时
扫描TODO/FIXME/HACK注释 → 检查存在时间 → 标记超过N天的注释为过时
示例: 代码注释"// TODO: implement this later"(30天前创建) → 检测结果:注释过时
解析文档中的文件路径引用 → 检查文件是否存在 → 标记引用已删除文件的文档
示例: 文档引用"参见src/utils/helper.js" | 实际状态:文件已删除 → 检测结果:引用失效
解析API文档端点定义 → 扫描代码实际实现 → 对比参数/返回值/错误码
示例: API文档:"POST /api/users,参数{name,email}" | 实际代码:"{name,email,phone}" → 检测结果:文档缺失phone参数
Parse code references in documentation (file paths / function names / API endpoints) → Check whether code exists and behavior is consistent
Example: Document states "API /api/users returns user list" | Actual code returns user details (including orders) → Result: Documentation outdated
Scan TODO/FIXME/HACK comments → Check creation time → Mark comments older than N days as stale
Example: Code comment "// TODO: implement this later" (created 30 days ago) → Result: Comment outdated
Parse file path references in documentation → Check if files exist → Flag documents referencing deleted files
Example: Document references "see src/utils/helper.js" | Actual status: File deleted → Result: Broken reference
Parse API endpoint definitions in docs → Scan actual code implementation → Compare parameters / return values / error codes
Example: API doc: "POST /api/users, params {name,email}" | Actual code: "{name,email,phone}" → Result: Doc missing phone parameter
扫描(文档目录/代码注释/API文档) → 对比(代码引用/API定义/行为描述) → 分类(问题类型/严重程度/优先级) → 执行(更新文档/创建PR/删除废弃)
Scan (documentation directory / code comments / API docs) → Compare (code references / API definitions / behavior descriptions) → Classify (issue type / severity / priority) → Execute (update documentation / create PR / delete deprecated)
# 文档园丁报告 - YYYY-MM-DD
## 扫描范围: docs/(XX文件) / src/
## 发现问题
### Critical(必须修复): 文件 | 问题 | 建议
### Warning(建议修复): 文件 | 问题 | 建议
### Info(可选修复): 文件 | 问题 | 建议
## 执行结果: 更新X项 | 创建PR X项 | 跳过X项
# Document Gardener Report - YYYY-MM-DD
## Scan Scope: docs/(XX files) / src/
## Issues Found
### Critical(Must Fix): File | Issue | Suggestion
### Warning(Should Fix): File | Issue | Suggestion
### Info(Optional Fix): File | Issue | Suggestion
## Execution Results: Updated X items | Created PR X items | Skipped X items
doc-gardener-config.yaml)doc_gardener:
scan:
docs_paths: ["docs/", "*.md"]
code_paths: ["src/"]
exclude: ["node_modules/", "dist/"]
staleness:
todo_max_age_days: 30
doc_max_age_days: 90
execution:
auto_update: true
create_pr: true
max_pr_per_run: 3
doc_gardener:
scan:
docs_paths: ["docs/", "*.md"]
code_paths: ["src/"]
exclude: ["node_modules/", "dist/"]
staleness:
todo_max_age_days: 30
doc_max_age_days: 90
execution:
auto_update: true
create_pr: true
max_pr_per_run: 3
证据先行: 标记文档为"过时"前必须有明确证据(代码已删除/API已变更/行为已修改),不得基于猜测判定。
最小化干预: 文档修复采用最小改动原则,只更新确实过时的部分,不得借机重写整个文档。
分类处置: 按Critical/Warning/Info三级分类,Critical立即修复,Warning创建任务,Info记录观察。
不删除仅标记: 废弃文档应标记"Deprecated"而非直接删除,删除需用户确认。
闭环追踪: 每个问题都必须有明确状态(已修复/待修复/已忽略)和处置记录。
违规示例: ❌ 因为"看起来很久没更新"就标记过时 | ❌ 发现一个过时就重写整个文档 | ❌ 全部标为Critical | ❌ 直接删除引用已删除文件的段落 | ❌ 生成问题清单但不跟踪
合规示例: ✅ 标记过时时附证据:"引用的src/utils/helper.js在commit abc123中被删除" | ✅ 只更新过时参数,保留其余部分 | ✅ Critical=影响功能运行,Warning=误导理解,Info=形式问题 | ✅ 先归档到deprecated/目录 | ✅ 报告每个问题都有状态列
Evidence First: Before marking a document as "outdated", there must be clear evidence (code deleted / API changed / behavior modified). Never mark based on speculation.
Minimal Intervention: Document fixes follow the principle of minimal changes — only update truly outdated parts. Do not use this as an opportunity to rewrite the entire document.
Classified Disposition: Classify into three levels: Critical / Warning / Info. Critical = fix immediately, Warning = create task, Info = record and observe.
Mark, Don't Delete: Deprecated documents should be marked "Deprecated" rather than directly deleted. Deletion requires user confirmation.
Closed-Loop Tracking: Every issue must have a clear status (fixed / pending / ignored) and disposition record.
Violation Examples: ❌ Mark as outdated because "looks like it hasn't been updated in a while" | ❌ Rewrite entire document upon finding one outdated item | ❌ Mark everything as Critical | ❌ Directly delete paragraphs referencing deleted files | ❌ Generate issue list without tracking
Compliant Examples: ✅ When marking outdated, attach evidence: "Referenced src/utils/helper.js was deleted in commit abc123" | ✅ Only update outdated parameters, preserve the rest | ✅ Critical = affects functionality, Warning = misleading understanding, Info = formatting issue | ✅ Archive to deprecated/ directory first | ✅ Report includes status column for every issue
| # | Trap / 陷阱 | Question | Action |
|---|---|---|---|
| 1 | "这个文档肯定过时了,直接标吧" / "This doc is definitely outdated, just mark it" | 无证据判断可能错误,误标浪费时间 / Uninformed judgment may be wrong, wasting time on false positives | 必须找到具体的代码/文档不一致证据 / Must find specific code/documentation inconsistency evidence |
| 2 | "趁机会把文档重写了吧" / "Let's rewrite the doc while we're at it" | 重写会引入新错误且超出职责 / Rewriting introduces new errors and exceeds scope | 只做必要修正,大规模重构单独建议 / Only make necessary fixes; suggest large refactoring separately |
| 3 | "都是小问题,统一标Warning吧" / "These are all minor, just mark them Warning" | 失去分级导致严重问题得不到及时处理 / Losing severity levels causes serious issues to go unaddressed | 严格按影响程度分级 / Classify strictly by impact severity |
| 4 | "旧文档占空间,删掉算了" / "Old docs waste space, just delete them" | 删除不可逆,可能丢失有价值信息 / Deletion is irreversible, may lose valuable information | 先归档deprecated/,保留期(如90天)后再确认 / Archive to deprecated/ first, confirm after retention period (e.g., 90 days) |
| 5 | "报告生成了工作就完成了" / "Report generated, job done" | 发现问题不跟踪等于没做 / Finding issues without tracking is as good as doing nothing | 报告必须含处置建议和跟踪机制 / Report must include disposition suggestions and tracking mechanism |
常见陷阱 / Common Traps:
"过度标记"陷阱 / "Over-marking" Trap: 大量非关键问题标记过时,制造"狼来了"效应 → 严格证据标准:每个标记必须附具体证据 / Mass non-critical issues marked outdated creates "cry wolf" effect → Strict evidence standard: every mark must attach specific evidence
"大修诱惑"陷阱 / "Major Overhaul" Trap: 借清理之名行重构之实 → 单次修改比例上限(如不超过20%) / Using cleanup as excuse for refactoring → Single-change modification cap (e.g., max 20%)
"分级扁平"陷阱 / "Flat Classification" Trap: 所有问题同一级别 → 量化标准:Critical=影响功能,Warning=误导理解,Info=形式 / All issues same level → Quantified standard: Critical=affects function, Warning=misleading understanding, Info=formatting
"删除冲动"陷阱 / "Deletion Impulse" Trap: 倾向删除而非归档 → 强制流程:删除前必须移至deprecated并保留一周期 / Tendency to delete rather than archive → Mandatory process: must move to deprecated before deletion with retention period
🔴 CRITICAL → 立即停止,报告问题详情,等待指示 / Stop immediately, report problem details, await instructions
🟡 WARN → 记录警告,尝试自动修复,在报告中标注 / Log warning, attempt auto-fix, annotate in report
🔵 INFO → 记录信息,正常继续 / Log information, continue normally