name: pin description: 管理项目情报（Project Information）文档系统。当需要创建、读取、更新或导航项目文档时使用，包括业务知识（需求文档、操作手册）、技术文档（架构、开发环境、代码地图、研究记录）、UI设计（设计图、切图）、规范文档（git 规范、代码规范、示例）和任务日志。在项目初始化、编写需求/技术/UI/规范文档、管理开发任务、或需要了解项目上下文时触发。

Pin - 项目情报管理

概述

Pin 是一个结构化的项目文档管理系统，以 pin-docs/ 为根目录，帮助 AI 从业务、技术、设计、规范、任务五个维度理解和管理项目信息。

核心目录结构：

pin-docs/
├── 0-业务知识/        # 业务知识：需求文档、操作手册
│   ├── 0-索引.md
│   ├── 1-需求文档/    # PRD，按业务领域组织
│   └── 2-操作手册/    # 用户视角的操作指南
├── 1-技术文档-X/      # 技术架构、开发环境、代码地图、研究记录
│   ├── 0-索引.md
│   ├── 1-技术架构.md
│   ├── 2-开发环境.md
│   ├── 3-代码地图/
│   └── 4-研究记录/
├── 2-UI设计/          # UI设计图、UI切图
│   ├── 0-索引.md
│   ├── 1-UI设计图/
│   └── 2-UI切图/
├── 3-规范文档-X/      # git 规范、代码规范、示例
│   ├── 0-索引.md
│   ├── 1-git规范.md
│   ├── 2-代码规范.md
│   └── 3-示例/
├── 4-任务日志/        # 开发任务管理
│   ├── 0-索引.md
│   ├── 0-未开始/
│   ├── 1-进行中/
│   └── 2-已完成/
└── 5-assets/          # 图片、截图等公共资源

完整的结构和文档定义参考 references/idea.md。

核心工作流

1. 项目初始化

当用户要求初始化 Pin 文档系统时：

检查当前项目是否存在 pin-docs/ 目录
如果不存在，按以下步骤创建目录骨架：
- 创建六大类目录：0-业务知识/、1-技术文档-X/、2-UI设计/、3-规范文档-X/、4-任务日志/、5-assets/
- 创建各子类目的子目录（参见上方目录树）
为每个大类创建对应的 0-索引.md（参考 references/templates/index-template.md）
初始化完成后，引导用户填写第一份文档（如 overview 或技术架构）

2. 文档导航

Pin 使用 0-索引.md 作为每层目录的导航入口。永远优先读取索引文件来定位目标文档，而不是扫描整个目录。

导航流程：

读取目标层级的 0-索引.md 了解有哪些文档可用
根据用户意图匹配关键词，找到对应文档路径
读取目标文档

例如搜索"用户登录"相关文档：

先读 0-业务知识/0-索引.md 找到相关需求文档
再读 1-技术文档-X/0-索引.md 找到相关代码地图
最后读取具体文档内容

3. 创建文档

创建新文档时：

确定文档类型，使用对应的模板（见下方文档类型指南）
放置到正确的路径，遵循命名规范
更新所在层级的 0-索引.md，添加新文档的关键词、摘要、路径

命名规范：

需求文档/操作手册：<序号>-<业务领域>.md（操作手册与需求文档的序号和领域名保持一致）
代码地图：<序号>-<业务领域>.md，公共组件为 0-公共组件.md
任务目录：<yyMMdd>-<HHmm>-<任务标题>
示例文档：<序号>-<示例名称>.md

4. 更新文档

先读取现有内容
在对应章节增量更新，保持文档精简
如有需要，更新 0-索引.md 中的摘要

原则：文档内容简明扼要，表达关系和流程时使用 mermaid 图。不要在文档中记录代码中显而易见的信息（如属性名、方法名）。

5. 任务管理

任务有三种状态：未开始 → 进行中 → 已完成

创建新任务：

在 4-任务日志/0-未开始/ 下创建目录 <yyMMdd>-<HHmm>-<任务标题>
使用模板创建 task.md（任务描述）、plan.md（开发计划）
更新 4-任务日志/0-索引.md

任务状态流转：

将任务目录从一个状态文件夹移动到下一个（如从 0-未开始 移到 1-进行中）
更新 result.md（完成任务时）
更新 4-任务日志/0-索引.md

文档类型指南

注意：写任何文档前，一定要阅读并理解文档定义 references/idea.md。

0-业务知识/1-需求文档

用途：记录业务需求、领域知识、边界上下文。

关键文件：

0-overview.md：项目背景、通用语言（Ubiquitous language）、领域清单、领域关系图。模板：references/templates/overview.md
<业务领域>.md：单一业务领域的需求描述。模板：references/templates/requirement.md

0-业务知识/2-操作手册

用途：从用户角度描述系统功能和使用方法。

结构：与需求文档保持领域对应。

模板：references/templates/operation-manual.md

1-技术文档-X/1-技术架构.md

用途：记录技术栈、微服务清单、模块关系。

内容：开发语言、重要依赖、微服务清单、模块关系。保持精简。

模板：references/templates/tech-architecture.md

1-技术文档-X/2-开发环境.md

用途：本地开发指南——如何启动、调试、使用外部资源、构建、CI/CD。

模板：references/templates/dev-environment.md

1-技术文档-X/3-代码地图

用途：代码索引，帮助 AI 定位代码。

结构：按业务领域组织，每个领域一个文件。包含代码清单、实体关系、调用关系、API 清单。

特殊：0-公共组件.md 单独记录公共领域的代码索引。

模板：references/templates/code-map.md

1-技术文档-X/4-研究记录

用途：保存技术研究沉淀，帮助 AI 复用以前的技术成果，避免重复踩坑。

内容范围：开发中遇到的技术坑点、难以处理的 BUG、复杂函数逻辑/调用链分析、与项目相关的技术文章等。

结构：以 <研究主题>/research.md 的形式组织，每个研究主题一个子目录。

模板：references/templates/research.md

2-UI设计

用途：存放 UI 设计图和前端切图，帮助 AI 理解界面设计和视觉规范。

1-UI设计图/：产品设计稿、界面流程图、交互原型截图等
2-UI切图/：前端开发使用的切图资源（图标、背景图等）

3-规范文档-X

用途：告知 AI 应遵循的工程规范。

1-git规范.md：分支规范、commit 规范。模板：references/templates/git-convention.md
2-代码规范.md：总体要求和公共规范。模板：references/templates/code-convention.md
3-示例/：具体代码示例。模板：references/templates/example.md

0-索引.md

用途：每层目录的导航入口，列出该目录下所有文档的关键词、摘要、路径。

模板：references/templates/index-template.md

任务文档

每个任务目录下：

task.md：任务描述。模板：references/templates/task.md
plan.md：开发计划。模板：references/templates/plan.md
result.md：任务结果（完成时填写）。模板：references/templates/result.md

5-assets

用途：存放图片、截图等公共资源。

文档中需要引用图片时，使用相对路径（如 ../5-assets/login-flow.png）指向 5-assets/ 目录下的文件。

文档编写原则

简明扼要：只记录 AI 需要但无法从代码中直接获得的信息
用图表达：关系、流程使用 mermaid 绘制
避免重复：代码中显而易见的信息（属性名、方法名、详细逻辑）不要写入文档
保持一致性：需求文档、操作手册、代码地图的业务领域命名保持一致
公共资源：图片、截图等存放在 5-assets/ 目录下，文档中使用相对路径引用

chanjarster/skills