# Project Knowledge Hierarchy

> 项目知识库分层维护技能，根据四层架构（项目层→技术层→资产层 + 原始层）生成标准化项目文档目录结构。docs/ 下四层采用中文目录命名，每个目录需配套 index.md 索引文件，所有文档需附带 YAML 元数据（文档编号、标题、类型、状态、日期、作者）。原始层作为信息源头另行存储。支持初始化和增量维护。当用户需要创建项目知识管理文档、维护项目资产文档、规划项目文档体系、生成项目文档目录时使用此技能。

- Skill: `wuchubuzai2018/project-knowledge-hierarchy` (Agent Skill, multi-file: 10 files)
- Install (CLI): `npx skillmds add wuchubuzai2018/project-knowledge-hierarchy`
- Raw SKILL.md: https://api.skillmd.com/api/skills/wuchubuzai2018/project-knowledge-hierarchy/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: wuchubuzai2018 (https://skillmd.com/u/wuchubuzai2018)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/wuchubuzai2018/project-knowledge-hierarchy

---


# Project Knowledge Hierarchy

## 介绍

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

- **项目层 (Project Layer)** - 业务方向、核心流程、架构设计、决策记录
- **技术层 (Technology Layer)** - 中间件、数据库设计、编码规范、第三方库、接口文档
- **资产层 (Assets Layer)** - 产品需求、技术方案、测试用例、Bug记录
- **原始层 (Raw Assets)** - 会议纪要、网页、聊天记录、录音转写等原始信息

前三层（项目层 → 技术层 → 资产层）遵循**单向依赖原则**：上层文档可引用下层文档，禁止反向依赖。
原始层不属于 `docs/` 三层结构的正式目录，而是上层文档的**信息源头**；原始材料经提炼后才能进入正式层级。

> 详细说明见 [`references/raw-layer.md`](./references/raw-layer.md)。

## 参考文件路由表

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

| 主题 | 路径 | 何时加载 |
|------|------|----------|
| 完整目录结构与子目录职责一览 | [`references/directory-structure.md`](./references/directory-structure.md) | 创建目录、规划结构、自定义模式选择子目录、查询子目录职责时 |
| 原始层详细说明（定义、关系、存储、提炼流程） | [`references/raw-layer.md`](./references/raw-layer.md) | 处理原始材料、回答原始层相关问题、决定存储位置时 |
| 增量维护指引（四步法、归档决策树、必做清单） | [`references/incremental-maintenance.md`](./references/incremental-maintenance.md) | 归档已有文档、新增文档走归档决策时 |
| 维护规范（命名、格式、元数据、索引、层级、版本） | [`references/maintenance-rules.md`](./references/maintenance-rules.md) | 检查违规、回答维护相关问题、做 AI 自检时 |
| Google OKF（Open Knowledge Format）介绍与对齐指引 | [`references/okf-intro.md`](./references/okf-intro.md) | 用户询问"OKF 是什么"或"是否兼容 OKF"、要求启用 OKF 字段时 |

## 执行步骤Workflow

### Step 1: 询问目录位置

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

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

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


### Step 2: 检查已有目录

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

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

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

> **原始层注意**：原始层不在 `docs/` 三层结构内（详见 `references/raw-layer.md`）；本步骤只检查 `docs/`，原始层存储位置由项目自定。

### Step 3: 选择生成模式

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

| 模式 | 说明 | 输出内容 | 是否包含原始层 |
|------|------|----------|----------------|
| 完整模式（推荐） | 生成全部四层结构 | 13 个三层子目录 + 3 个层级 `index.md` + 13 个子目录 `index.md` + 原始层目录 + 原始层 `README.md` | **包含** |
| 单层模式 | 只生成指定层级 | 指定层的子目录 + 层级 `index.md` + 该层子目录 `index.md` | 不包含 |
| 自定义模式 | 用户选择需要的子目录 | 用户勾选的子目录 + 对应 `index.md` | 可选 |
| 原始层模式 | 仅初始化原始层 | 原始层目录 + 来源子目录 + `README.md` | 包含 |

询问用户：

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

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

> **完整模式默认包含原始层**：原始层是项目知识的源头，长期项目通常都需要；完整模式自动建好，后续随时可往里放原始材料。

### Step 4: 创建目录结构

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

```bash
# 示例：创建完整四层结构（中文目录名）
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-Bug记录}
```

> **原始层位置**：四种推荐方案（`docs/00-原始层/` / 仓库独立目录 / 外部知识库）详见 `references/raw-layer.md` 存储位置建议。

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

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

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

子目录含义与命名规范：

| 子目录 | 用途 | 文件命名示例 |
|--------|------|--------------|
| `meetings/` | 会议纪要 | `2026-08-30-meeting-产品周会.md` |
| `interviews/` | 用户/客户访谈 | `2026-08-25-interview-王先生.md` |
| `web-clips/` | 网页资料 | `2026-08-20-web-AI-竞品分析.md` |
| `chat-logs/` | 聊天记录 | `2026-08-15-chat-订单重构讨论.md` |
| `transcripts/` | 录音/录像转写 | `2026-08-10-transcript-客户访谈.md` |
| `misc/` | 其他杂项 | `2026-08-05-misc-需求工单.md` |

> **按日期分子目录**是另一种合法做法（如 `docs/raw/2026-Q3/`、`docs/raw/2026-Q4/`），适用于来源类型单一的项目。

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

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

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

1. 复制 `references/raw-layer.md` 内「原始层层说明 README.md 模板」代码块
2. 按项目实际选择的子目录调整「子目录结构」表格
3. 按项目实际来源类型调整「文件命名规范」表格
4. 删除模板中的占位说明段落（如「### 使用方式」）
5. 将 `README.md` 放在原始层**根目录**下，**不要放在某个子目录下**

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

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

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

### Step 5: 初始化 index.md 文件

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

#### docs/index.md（顶层总览）

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

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

#### 各层 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/directory-structure.md)「子目录职责一览」一节。原始层目录由项目自定，详见 [`references/raw-layer.md`](./references/raw-layer.md) 存储位置建议。

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

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

### 字段定义（速查）

#### 核心 6 字段（必须）

| 字段 | 必填 | 说明 | 取值建议 |
|------|------|------|----------|
| `文档编号` | ✅ | 文档唯一标识，全局不重复 | 格式 `DOC-{层级编码}-{子目录序号}-{3 位序号}`，例如 `DOC-PRJ-01-001`、`DOC-TECH-02-007`、`DOC-AST-04-015` |
| `标题` | ✅ | 文档标题 | 与正文一级标题保持一致 |
| `类型` | ✅ | 文档类型 | `总览` / `索引` / `需求` / `方案` / `设计` / `规范` / `接口` / `测试` / `缺陷` / `决策` / `会议纪要` / 其他 |
| `状态` | ✅ | 文档生命周期状态 | `草稿` / `评审中` / `现行` / `已废弃` |
| `日期` | ✅ | 最近更新日期 | 格式 `YYYY-MM-DD` |
| `作者` | ✅ | 文档作者或作者组 | 个人姓名或团队名，如 `张三` / `架构组` |

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

| 字段 | 推荐度 | 说明 | 取值建议 |
|------|--------|------|----------|
| `描述` | ⭐⭐⭐ | 单句摘要，用于 `index.md` 清单、搜索摘要、预览 | 一句话，≤ 80 字 |
| `标签` | ⭐⭐⭐ | 跨切面分类标签，便于按主题/模块检索 | YAML 列表，如 `[订单, 收入, 销售]` |

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

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

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

### 层级编码对照

| 层级 | 编码 |
|------|------|
| 项目层 | `PRJ` |
| 技术层 | `TECH` |
| 资产层 | `AST` |

### AI 执行流程

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

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