project-docs-management

name	project-docs-management
description	项目结构化知识库初始化，基于渐进式披露原则从零搭建AGENTS.md、架构.md和文档目录。仅用于首次建立知识库，后续维护和文档整理请使用 doc-gardener 技能。当用户提到"建立知识库""初始化文档""搭建文档结构"时使用。

项目结构化知识库初始化

本技能仅用于首次搭建。知识库建好后的所有维护（巡检、整理散乱文档、审计模块旧文档）统一由 doc-gardener 技能负责。

核心理念

给 Agent 一张地图，而不是一本说明书。

1. 渐进式披露：AGENTS.md 是 Cursor 原生 AI 入口文件（≤250行），指向 文档/ 深层文档
2. 不在仓库里 = 不存在：把隐性知识搬入仓库
3. 为 Agent 可读性优化：文档不含示例代码，充分信任大模型

命名规范

一切使用中文命名：文件、目录、导航文档、架构文档全部中文，.md 格式。

知识库目录结构

项目根目录/
├── AGENTS.md              # Cursor 原生 AI 入口文件（≤250行）
├── 架构.md                # 项目鸟瞰图
├── 文档/                  # 结构化知识库（唯一真相源）
│   ├── 设计文档/          # 标注验证状态
│   ├── 核心信念/          # 团队工程原则与长期规范
│   ├── 执行计划/
│   │   ├── 进行中/
│   │   ├── 已完成/
│   │   └── 技术债务/
│   ├── 产品规格/
│   ├── 参考资料/
│   ├── 质量评分/
│   ├── 凭据与配置/        # 开发阶段直接记录明文
│   └── 变更日志/

AGENTS.md 编写规则

Cursor 原生文件，AI 助手启动时自动读取，是 AI 理解项目的唯一入口。

严格 ≤250 行。必含：项目概述、技术栈、知识库索引、目录结构、标准模块结构、核心编码规范、部署约束、凭据位置。 禁止放入：详细 API 文档、完整部署步骤、数据库 Schema、冗长示例代码。

架构.md 编写规则

必含：业务域划分、代码包分层、模块依赖关系、部署拓扑（容器/端口/域名）、数据存储。

文档分类规则

• 设计文档：开头必须标注 验证状态: ✅已验证 | ⚠️部分验证 | ❌未验证 | 🚧设计中
• 核心信念：不随任务变化的长期约定
• 执行计划：复杂任务签入 进行中/，完成移至 已完成/，技术债务单独记录
• 质量评分：各模块成熟度（⭐~⭐⭐⭐⭐⭐）、改动风险
• 凭据与配置：Token/密码/API Key 集中明文记录
• 变更日志：跨模块的重大变更

初始化工作流（使用子 agent 并行）

必须使用 Task 工具启动子 agent 并行处理，不指定 model 参数（继承父级模型）。

阶段1：搭建结构 + 扫描现有文档（并行）

同时启动 2 个子 agent：

子 agent	任务
agent-A	创建 文档/ 完整目录结构（含所有子目录）
agent-B	递归扫描项目下所有 .md 文件，生成完整文档清单（路径、大小、修改时间、初步分类）

阶段2：编写核心文档 + 分类现有文档（并行）

根据扫描结果，启动 3-4 个子 agent：

子 agent	任务
agent-C	编写 架构.md（读取代码结构、docker-compose、nginx配置）
agent-D	编写 AGENTS.md（基于架构.md和文档/结构，含知识库索引+编码规范+模块结构模板）
agent-E	将系统级文档迁移到 文档/ 对应子目录
agent-F	整合凭据信息（读取 .env、credentials 文件，生成凭据总览）

阶段3：收尾

1. 为设计文档补验证状态头部
2. 建立初始质量评分
3. 生成初始化审计报告存入 文档/变更日志/
4. 备份原始文档目录

详细参考

• 各类文档完整模板，见 reference.md
• 基于瑞小美AiOS项目的实际示例，见 examples.md