Menu
维护 pi-go 项目文档结构与一致性。当用户提到'维护一下文档'、'更新文档'、'文档整理一下'、'docs 该整理了'、'同步文档和代码'、'整理 docs 目录'等意图时加载此 skill。
Instalar com Codex ou Claude Copie este prompt, cole no Codex, Claude ou outro assistente e deixe que ele revise a página da skill e instale para você.
Baseado na classificação ocupacional SOC
| name | docs-maintainer |
| description | 维护 pi-go 项目文档结构与一致性。当用户提到'维护一下文档'、'更新文档'、'文档整理一下'、'docs 该整理了'、'同步文档和代码'、'整理 docs 目录'等意图时加载此 skill。 |
绝对路径：/Users/weijian/Desktop/develop/test/pi/pi-go
所有路径基于此根目录，下文简称 {pi-go}。
本 skill 维护以下目录结构，迁移时必须遵守：
docs/
├── README.md # 文档总索引
├── PROJECT_CONTEXT.md # 项目上下文快照
├── PRODUCT_ROADMAP.md # 产品路线图（长期）
├── CONTRIBUTING.md # 贡献指南（长期）
├── deploy.md # 部署说明（长期）
│
├── references/ # 稳定查阅资料（接口/集成/项目快照）
│
├── decisions/ # 当前采纳判断（会演进，但比 research 更接近团队共识）
│
├── research/ # 外部项目调研原始报告（天然会过期）
│
├── dev/ # 开发文档（4-agent 流水线产出）
│ └── {topic}/ # 一个主题一个目录
│ ├── proposal.md # 计划 agent 产出
│ ├── review.md # 审核 agent 产出
│ └── execution-plan.md # 确认后的执行文档
│
└── archive/ # 已完成的开发主题
└── {topic}/ # 整个目录从 dev/ 移入
每个 dev/ 下的文档必须有 YAML 头：
---
status: draft | reviewed | approved | done
author: plan-agent | review-agent | exec-agent | research-agent
created: YYYY-MM-DD
updated: YYYY-MM-DD
reviewer: review-agent # review.md 专有
review-status: pending | approved | rejected | needs-revision # review.md 专有
depends-on: [] # 可选
---
状态流转：draft → reviewed → approved → done（rejected/needs-revision 回到 draft）
| 性质 | 归属 | 示例 |
|---|---|---|
| 长期有效的项目级文档 | docs/ 根目录 | PROJECT_CONTEXT、ROADMAP、CONTRIBUTING |
| 稳定查阅资料 | docs/references/ | 第三方集成参考、项目快照、接口说明 |
| 基于调研得出的当前采纳判断 | docs/decisions/ | skills vs application、goal/compact 取舍 |
| 外部项目调研原始分析 | docs/research/ | 竞品分析、框架对比、源码调查 |
| 4-agent 流水线产出的开发文档 | docs/dev/{topic}/ | 提案、审核、执行计划 |
| 已完成的开发主题 | docs/archive/{topic}/ | 已归档的执行计划 |
当用户说"文档有没有过时"、"快速检查一下文档"时，可以跳过完整的 4 阶段流程，只做以下快速检查：
find docs/ -name "*.md" | sort vs docs/README.md 中列出的文件dev/ 下每个主题的最新 updated 日期 + status，标记满足归档条件的输出一个简洁的清单即可，不做修改。
find {pi-go}/internal -type f -name "*.go" | head -80
grep -r "^type.*interface {" {pi-go}/internal --include="*.go" -l
grep -r "^func New" {pi-go}/internal --include="*.go" | head -30
不要写死文件列表，用 find 动态发现：
find {pi-go}/docs -name "*.md" -type f | sort
同时扫描根目录 README：
head -50 {pi-go}/README.md
对每个文件：
dev/ 下的文档：检查元信息头是否完整、状态是否合理docs/README.md：检查索引是否覆盖所有文件docs/PROJECT_CONTEXT.md：检查与源码一致性{pi-go}/README.md：检查与源码一致性（见下方专项检查）archive/ 下的文件：只读头部，判断归档是否合理对每份文档做以下检查：
| 检查项 | 判断标准 |
|---|---|
| 索引缺失 | docs/README.md 没有列出存在的文件 |
| 索引多余 | docs/README.md 列出了但文件已不存在 |
| 内容过时 | 文档描述与当前源码不一致 |
| 归档判断 | dev/ 下满足归档条件的主题（见下方归档判断规则） |
| 元信息头 | dev/ 下的文档缺少 YAML 头或字段不完整 |
| 归属错误 | 文档放在错误的目录（如参考资料放在根目录） |
| 决策/调研混放 | 带明确采纳建议与路线图的文档放在 research/ 或 references/ |
| PROJECT_CONTEXT | 架构、能力表、文件索引与实际代码不匹配 |
| 根 README 过时 | README.md 中的 API 路由、工具/命令列表、环境变量、代码统计与实际代码不一致 |
| 已完成未归档 | dev/ 下描述的改动已出现在 main 分支代码中，但目录仍在 dev/ |
满足以下任一条件，即可建议归档：
doneinternal/ 对应文件中（通过 git log + grep 交叉验证）updated 日期距今超过 30 天，且 execution-plan.md 的 status 为 approved 或 done注意：
deferred状态的主题留在dev/，不归档。
dev/ 主题的状态列internal/ 目录结构变化时更新根目录 README.md 是项目的门面，需要与代码保持同步。检查以下内容：
internal/server/server.go 中注册的路由对比internal/agents/coding/commands/builtins.go 中注册的命令对比internal/tools/ 下的工具文件对比internal/config/config.go 中的环境变量对比internal/ 下的包结构对比，新增能力需补充go.mod 中的版本一致满足以下条件时，将 dev/{topic}/ 整个目录移入 archive/：
status 均为 donemv {pi-go}/docs/dev/{topic} {pi-go}/docs/archive/{topic}
不要归档：PROJECT_CONTEXT、ROADMAP、CONTRIBUTING、deploy.md
文档放错目录时，移到正确位置：
references/decisions/research/dev/{topic}/dev/ 下缺少 YAML 头的文档，根据内容推断并补全。
## 文档维护报告 {YYYY-MM-DD}
### 已修正
- [更新] docs/README.md：补充了 X 的索引
- [归档] dev/zzz/ → archive/zzz/
- [更新] PROJECT_CONTEXT.md：核心能力表新增 W
- [更新] README.md：API 路由表新增 /models 等端点
- [归属] feishu-ref.md → references/
### 无需修正
- CONTRIBUTING.md：内容准确
- deploy.md：内容准确
### 需人工确认
- XXX.md：描述了尚未确定的设计方向，建议确认后更新