project-knowledge-hierarchy

Imported from wuchubuzai2018/expert-skills-hub (skills/project-knowledge-hierarchy/SKILL.md). Install upstream with npx skills add wuchubuzai2018/expert-skills-hub --skill project-knowledge-hierarchy. Copyright stays with the author.

Project Knowledge Hierarchy

介绍

项目知识库分层模型将项目知识分为 4 个层级，从上到下依次为：

• 项目层 (Project Layer) - 业务方向、核心流程、架构设计、决策记录
• 技术层 (Technology Layer) - 中间件、数据库设计、编码规范、第三方库、接口文档
• 资产层 (Assets Layer) - 产品需求、技术方案、测试用例、踩坑与经验沉淀
• 原始层 (Raw Layer) - 蒸馏原料池：会议录音转写、网页资料、聊天记录等未提炼的一手材料

前三层（项目层 → 技术层 → 资产层）遵循单向依赖原则：上层文档可引用下层文档，禁止反向依赖。

原始层是第 4 层，位于 docs/04-原始层/，必须初始化。它的定位是蒸馏原料池：丢进去一段会议录音转写，Agent 读取后自动提炼出 PRD 塞进 03-资产层/01-产品需求，或提炼出 ADR 塞进 01-项目层/04-决策记录。

详细说明见 references/raw-layer.md。

触发时机（何时加载本技能）

本技能既是"建目录"的工具，也是"读写项目知识"的工作流约定。以下情形必须先加载本技能再行动：

硬性约束：上述场景中"任务开始前读上下文"与"解决后写沉淀"属于闭环，不可只做前半段——修完问题不沉淀，等于下次还要重新踩同一个坑。

参考文件路由表

为保持主文件精简，下列内容按需加载：

执行步骤Workflow

Step 1: 询问目录位置

首先询问用户文档目录的创建位置：

请确认文档目录的创建位置，默认在当前工程的 docs 目录下创建。

根据用户回答确定目标路径，如用户无输入，默认在 docs/ 目录下创建。

Step 2: 检查已有目录

在创建前检查目标路径是否已存在文档结构：

# 检查目标目录是否已存在
if [ -d "$TARGET_DIR" ]; then
  echo "检测到已有目录结构，将仅创建缺失的目录和文件，不会覆盖已有内容。"
fi

如果目录已存在，进入增量模式：只创建缺失的子目录，不覆盖已有的 index.md。

原始层注意：原始层是 docs/ 内的第 4 层（默认 docs/04-原始层/），必须初始化；检查时若发现缺失，同样按增量模式补建（详见 references/raw-layer.md）。

Step 3: 选择生成模式

根据用户需求和项目类型选择模式：

询问用户：

请选择生成模式：完整模式（推荐）/ 单层模式 / 自定义模式 / 原始层模式？

如用户无明确选择，默认使用完整模式。

原始层强制初始化：无论选择哪种模式，原始层（蒸馏原料池）都必须创建。原始层是知识生产的上游入口——没有原料池，Agent 就无法自动蒸馏出 PRD/ADR 等正式文档。用户若明确表示不需要，先向用户确认其意图，再跳过，并在项目说明中记录该例外。

Step 4: 创建目录结构

根据用户的系统环境，创建目录（使用 -p 确保幂等，已有目录不受影响）：

# 示例：创建完整四层结构（中文目录名）
mkdir -p docs/01-项目层/{01-项目概览,02-核心流程,03-架构设计,04-决策记录}
mkdir -p docs/02-技术层/{01-中间件配置,02-数据库设计,03-编码规范,04-第三方库,05-接口文档}
mkdir -p docs/03-资产层/{01-产品需求,02-技术方案,03-测试用例,04-踩坑与经验沉淀}
# 原始层（蒸馏原料池）：必须初始化
mkdir -p docs/04-原始层/{01-会议记录,02-用户访谈,03-网页资料,04-聊天记录,05-录音转写,06-其他杂项}

原始层位置：默认 docs/04-原始层/（第 4 层，与三层同库）；若用户明确要求隔离，可改为仓库独立目录（如 notes/raw/）或外部知识库，详见 references/raw-layer.md 存储位置建议。

Step 4.2: 原始层专用目录初始化（创建按来源类型的子目录）

原始层目录创建后，应额外按来源类型分子目录（推荐做法，正常执行）：

  # 在原始层根目录下创建按来源类型分的子目录
mkdir -p docs/04-原始层/{01-会议记录,02-用户访谈,03-网页资料,04-聊天记录,05-录音转写,06-其他杂项}

子目录含义与命名规范：

按日期分子目录是另一种合法做法（如 docs/04-原始层/2026-Q3/），适用于来源类型单一的项目。

Step 4.3: 创建原始层层说明 README.md

原始层不建 index.md，但必须建 README.md 作为层说明（这是与前三层的关键区别），正常执行：

模板与子目录、命名规范说明见 references/raw-layer.md（内含完整可复制的 README 模板代码块）。AI 按以下流程生成：

1. 复制 references/raw-layer.md 内「原始层层说明 README.md 模板」代码块
2. 按项目实际选择的子目录调整「子目录结构」表格
3. 按项目实际来源类型调整「文件命名规范」表格
4. 删除模板中的占位说明段落（如「### 使用方式」）
5. 将 README.md 放在原始层根目录下，不要放在某个子目录下
6. 在 README 中保留「蒸馏路由」小节，说明本项目原料 → 产物的映射（如会议转写 → PRD / ADR）

Step 4.4: 建立蒸馏链路（原料 → 产物的默认映射）

原始层建好后，必须在项目内建立"原料 → 产物"的默认蒸馏路由，保证用户往原始层丢材料时 Agent 知道该蒸馏成什么、写到哪里：

蒸馏执行流程（详见 references/raw-layer.md「蒸馏流程」）：

1. 读取原料 — 读取原始层中的新材料（转写/纪要/聊天/网页）
2. 识别产物类型 — 按上表判定应产出 PRD / ADR / 技术方案 / 踩坑记录等
3. 抽取要点 — 从原料中抽取结构化要点（背景、目标、约束、结论）
4. 写入正式文档 — 在目标子目录新建文档，附完整 YAML 头部（templates/document.md）
5. 登记索引 — 在目标子目录 index.md「文档清单」追加条目
6. 回链原料 — 在正式文档正文末尾写入「## 原始资料」小节，指向原始层文件路径

强制约束：用户提供原始材料并要求"整理成文档"时，AI 必须执行蒸馏产出正式文档，而不是把原料复制进三层结构；原料文件保留在原始层不动。

Step 4.1: 创建目录索引 index.md

每个目录（包括三层根目录、每个子目录）都必须创建 index.md 作为目录索引，模板见下文 目录索引模板。AI 在初始化阶段必须为每个目录生成对应的 index.md，即使是空目录也要保留空索引表，便于后续追加。

原始层例外：原始层下的目录不创建 index.md，但应在原始层根目录创建 README.md 作为层说明（详见 references/raw-layer.md）。

Step 5: 初始化 index.md 文件

仅在 index.md 不存在时创建，避免覆盖用户已有内容。本步骤只处理 docs/ 三层结构，原始层跳过本步骤（原始层用 README.md）。

docs/index.md（顶层总览）

模板详见 templates/root-index.md。AI 在初始化时按以下流程生成：

1. 复制 templates/root-index.md 内的模板内容
2. 替换占位符（YYYY-MM-DD、[作者/作者组]）
3. 确认四层目录链接与项目实际层级一致（含原始层 docs/04-原始层/）

各层 index.md 模板（层根目录）

模板详见 templates/layer-index.md。AI 在初始化时为每个层级根目录生成：

1. 复制 templates/layer-index.md 内的模板内容
2. 替换占位符（[层级编码]、[层级名称]、YYYY-MM-DD、[作者/作者组]）
3. 按该层级实际子目录填写「目录说明」表格
4. 按该层特点撰写「归档指引」（通常 1-3 条）

各目录内容说明

完整子目录职责一览（三层 × 全部子目录）详见 references/directory-structure.md「子目录职责一览」一节。原始层子目录职责与蒸馏路由见 references/raw-layer.md。

目录索引模板（子目录 index.md）

每个子目录（如 01-项目概览/、02-数据库设计/ 等）都必须创建 index.md，作为该目录的文档清单入口。模板与字段说明详见 templates/subdir-index.md。

AI 在初始化与维护时的执行流程：

1. 复制 templates/subdir-index.md 内的模板内容
2. 替换占位符（[层级]、[子目录序号]、[子目录名称]、YYYY-MM-DD、[作者/作者组]）
3. 用一句话准确描述该子目录的归档范围
4. 删除示例行后，按实际文档条目填写「文档清单」表格（列固定为：编号 / 标题 / 状态 / 日期 / 文档）

强制约束：AI 在每次新增、修改或废弃具体文档时，必须同步更新对应目录 index.md 中的「文档清单」表格，确保索引与文件保持一致。

文档元数据规范（YAML 头部）

所有非 index.md 的具体业务文档，必须在文档开头附带 YAML 格式的元数据（位于 Markdown 起始的 --- 代码块中）。

完整模板（含字段定义、层级编码、占位符说明、完整示例）详见 templates/document.md。

字段定义（速查）

核心 6 字段（必须）

标准推荐字段（强烈推荐，借鉴自 OKF）

AI 默认应在生成文档时一并输出这两个字段，除非用户明确表示不需要。仅当用户要求"只要最小集"时，才退化为仅 6 字段。

扩展可选字段（按需启用）

借鉴自 OKF v0.2 的 resource / sources / stale_after，仅在场景需要时启用。完整说明见 references/okf-intro.md。

层级编码对照

原始层为蒸馏原料池，其中的材料保留原貌、不带 YAML 头部与文档编号，因此不设层级编码。

AI 执行流程

1. 新建业务文档时，先复制 templates/document.md 的标准模板（核心 6 字段 + 推荐 2 字段）
2. 替换所有占位符（特别注意 文档编号 全局唯一）
3. 主动为 描述 与 标签 生成合理内容：
   • 描述：从文档标题与首段提炼单句摘要（≤ 80 字）
   • 标签：从主题、所属模块、涉及技术栈抽取 3-6 个分类标签
4. 编写正文
5. 在所属子目录 index.md 的「文档清单」表格中追加对应行
6. 当 状态 或 日期 变更时，同步更新所属 index.md 中的记录

强制约束：AI 在生成任何业务文档（不是 index.md）时，必须先输出完整的 YAML 元数据块（含 描述 与 标签），再编写正文。若用户提供的文档缺失元数据，应主动补全（含 描述 与 标签）并提示用户确认。仅当用户明确要求"只要最小集"时，才退化为仅 6 字段。