project-knowledge-hierarchy

Project Knowledge Hierarchy

Introduction

The project knowledge base layered model divides project knowledge into 4 layers, from top to bottom as follows:

• Project Layer - Business direction, core processes, architecture design, decision records
• Technology Layer - Middleware, database design, coding standards, third-party libraries, API documentation
• Assets Layer - Product requirements, technical solutions, test cases, Bug records
• Raw Assets - Meeting minutes, web pages, chat records, audio transcriptions and other raw information

The first three layers (Project Layer → Technology Layer → Assets Layer) follow theone-way dependency principle: upper-layer documents may reference lower-layer documents, and reverse dependencies are prohibited. The Raw Layer does not belong to the docs/ formal directory of the three-layer structure, but is theinformation sourceof upper-layer documents; raw materials can only enter the formal layers after being refined.

For detailed explanations, see references/raw-layer.md。

Reference File Routing Table

To keep the main file concise, the following content is loaded on demand:

Topic	Path	When to Load
Overview of the complete directory structure and subdirectory responsibilities	references/directory-structure.md	When creating directories, planning structures, selecting subdirectories in custom mode, or querying subdirectory responsibilities
Detailed explanation of the Raw Layer (definition, relationships, storage, refinement process)	references/raw-layer.md	When processing raw materials, answering questions related to the Raw Layer, or deciding storage locations
Incremental maintenance guide (four-step method, archiving decision tree, must-do checklist)	references/incremental-maintenance.md	When archiving existing documents or following the archiving decision process for new documents
Maintenance standards (naming, format, metadata, index, hierarchy, version)	references/maintenance-rules.md	When checking violations, answering maintenance-related questions, or performing AI self-checks
Introduction to and alignment guide for Google OKF (Open Knowledge Format)	references/okf-intro.md	When the user asks "What is OKF" or "Is it compatible with OKF", or requests enabling OKF fields

Execution Steps Workflow

Step 1: Ask for the directory location

First ask the user where to create the documentation directory:

Please confirm the creation location of the documentation directory; by default it is created under the current project's docs directory.

Determine the target path based on the user's answer; if the user provides no input, by default create it under the docs/ directory.

Step 2: Check existing directories

Before creation, check whether the target path already has a documentation structure:

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

If the directory already exists, enter incremental mode: only create missing subdirectories, and do not overwrite existing index.md。

Raw Layer note: The Raw Layer is not within the docs/ three-layer structure (see references/raw-layer.mdfor details); this step only checks docs/, and the Raw Layer storage location is determined by the project itself.

Step 3: Select generation mode

Select a mode based on user needs and project type:

Mode	Description	Output Content	Whether to include the raw layer
Full mode (recommended)	Generate all four-layer structure	13 three-layer subdirectories + 3 layers index.md + 13 subdirectories index.md + raw layer directory + raw layer README.md	Included
Single-layer mode	Generate only the specified layer	Subdirectories of the specified layer + layers index.md + subdirectories of that layer index.md	Not included
Custom mode	User selects the needed subdirectories	User-checked subdirectories + corresponding index.md	Optional
Raw layer mode	Initialize only the raw layer	Raw layer directory + source subdirectories + README.md	Included

Ask the user:

Please select the generation mode: Full mode (recommended, includes raw layer) / Single-layer mode / Custom mode / Raw layer mode?

If the user has no clear preference, use Full mode by default.

Full mode includes the raw layer by default: The raw layer is the source of project knowledge and is usually needed for long-term projects; Full mode sets it up automatically, and raw materials can be placed there at any time later.

Step 4: Create the directory structure

Based on the user's system environment, create the directories (use -p to ensure idempotency, existing directories are unaffected):

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

Raw layer location: Four recommended options (docs/00-原始层/ / repository-independent directory / external knowledge base), see references/raw-layer.md storage location recommendations for details.

Step 4.2: Initialize the raw layer's dedicated directories (create subdirectories by source type)

After the raw layer directory is created,shouldadditionally create subdirectories by source type (recommended practice, perform normally):

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

Subdirectory meanings and naming conventions:

Subdirectory	Purpose	File naming example
meetings/	Meeting minutes	2026-08-30-meeting-产品周会.md
interviews/	User/customer interviews	2026-08-25-interview-王先生.md
web-clips/	Web materials	2026-08-20-web-AI-竞品分析.md
chat-logs/	Chat records	2026-08-15-chat-订单重构讨论.md
transcripts/	Audio/video transcripts	2026-08-10-transcript-客户访谈.md
misc/	Other miscellaneous	2026-08-05-misc-需求工单.md

Grouping subdirectories by dateis another valid approach (e.g. docs/raw/2026-Q3/、docs/raw/2026-Q4/), suitable for projects with a single source type.

Step 4.3: Create the raw layer README.md

Raw layerDo not create index.mdbutmust create README.md as the layer description (this is the key difference from the three layers), perform normally:

For templates and subdirectory/naming convention descriptions, see references/raw-layer.md(contains a complete, copyable README template code block). The AI generates it as follows:

1. Copy the "Raw layer README.md template" code block in references/raw-layer.md Adjust the "Subdirectory Structure" table according to the subdirectories actually selected for the project
2. Adjust the "File Naming Conventions" table according to the project's actual source types
3. Delete the placeholder description paragraphs in the template (such as "### Usage")
4. Place
5. Place README.md in the raw layerroot directory,do not place it in a subdirectory

Step 4.1: Create the directory index index.md

Every directory (including the three-layer root directory and each subdirectory) must create index.md as the directory index; see the template below 目录索引模板. During initialization, the AI must generate the corresponding index.mdfor each directory; even for empty directories, an empty index table must be retained for later additions.

Raw layer exception: directories under the raw layerdo not create index.mdbutshouldcreate in the raw layer root directory README.md as the layer description (see references/raw-layer.md）。

Step 5: Initialize the index.md file

Create only when index.md does not exist, to avoid overwriting existing user content. This step only handles the docs/ three-layer structure; the raw layer skips this step.

docs/index.md (top-level overview)

See the template for details templates/root-index.md. During initialization, the AI generates it according to the following process:

1. Copy templates/root-index.md the template content inside
2. Replace placeholders (YYYY-MM-DD、[作者/作者组]）
3. Confirm that the three-layer directory links match the project's actual hierarchy

index.md template for each layer (layer root directory)

See the template for details templates/layer-index.md. During initialization, the AI generates for each layer root directory:

1. Copy templates/layer-index.md the template content inside
2. Replace placeholders ([层级编码]、[层级名称]、YYYY-MM-DD、[作者/作者组]）
3. Fill in the "Directory Description" table according to the actual subdirectories of that layer
4. Write the "Archiving Guide" according to the characteristics of that layer (usually 1-3 items)

Description of contents of each directory

For a complete overview of subdirectory responsibilities (three layers × all subdirectories), see references/directory-structure.mdthe "Subdirectory Responsibilities Overview" section. Raw layer directories are defined by the project; see references/raw-layer.md Storage Location Recommendations.

Directory index template (subdirectory index.md)

Every subdirectory (such as 01-项目概览/、02-数据库设计/ etc.) must create index.md, as the document list entry point for that directory. See the template and field descriptions for details templates/subdir-index.md。

The AI's execution process during initialization and maintenance:

1. Copy templates/subdir-index.md the template content inside
2. Replace placeholders ([层级]、[子目录序号]、[子目录名称]、YYYY-MM-DD、[作者/作者组]）
3. Use one sentence to accurately describe the archiving scope of that subdirectory
4. After deleting the example rows, fill in the "Document List" table according to the actual document entries (the columns are fixed as: No. / Title / Status / Date / Document)

Mandatory constraint: whenever the AI adds, modifies, or deprecates a specific document, it must synchronously update the "Document List" table in the corresponding directory index.md , ensuring that the index and files remain consistent.

Document metadata specification (YAML header)

All specific business documents other than index.md must include YAML-format metadata at the beginning of the document(located at the start of Markdown in the --- code block).

See the complete template (including field definitions, hierarchy codes, placeholder descriptions, and complete examples) for details templates/document.md。

Field definitions (quick reference)

Core 6 fields (required)

Field	Required	Description	Suggested values
文档编号	✅	Unique document identifier, globally non-repeating	Format DOC-{层级编码}-{子目录序号}-{3 位序号}, for example DOC-PRJ-01-001、DOC-TECH-02-007、DOC-AST-04-015
标题	✅	Document title	Keep consistent with the first-level heading in the main text
类型	✅	Document type	总览 / 索引 / 需求 / 方案 / 设计 / 规范 / 接口 / 测试 / 缺陷 / 决策 / 会议纪要 / Other
状态	✅	Document lifecycle status	草稿 / 评审中 / 现行 / 已废弃
日期	✅	Last updated date	Format YYYY-MM-DD
作者	✅	Document author or author group	Individual name or team name, e.g. 张三 / 架构组

Standard recommended fields (strongly recommended, borrowed from OKF)

Field	Recommendation level	Description	Value suggestions
描述	⭐⭐⭐	One-sentence summary, used for index.md list, search summary, preview	One sentence, ≤ 80 characters
标签	⭐⭐⭐	Cross-cutting category tags, for retrieval by topic/module	YAML list, e.g. [订单, 收入, 销售]

AI By default, should be output together when generating documentsThese two fields, unless the user explicitly indicates they are not needed. Only when the user requests "minimal set only" should it degrade to only 6 fields.

Extended optional fields (enable as needed)

Borrowed from OKF v0.2's resource / sources / stale_after, enable only when the scenario requires it. For full description see references/okf-intro.md。

Level code reference

Level	Code
Project level	PRJ
Technical level	TECH
Asset level	AST

AI execution process

1. When creating a new business document, first copy templates/document.md thestandard template(core 6 fields + recommended 2 fields)
2. Replace all placeholders (pay special attention that 文档编号 is globally unique)
3. Proactively generate reasonable content for 描述 and 标签 :
   • 描述: Extract a one-sentence summary (≤ 80 characters) from the document title and first paragraph
   • 标签: Extract 3-6 category tags from the topic, module it belongs to, and technology stack involved
4. Write the body
5. In the subdirectory it belongs to index.md append the corresponding row to the "Document list" table
6. When 状态 or 日期 changes, synchronously update the record in the index.md it belongs to

Mandatory constraint: When AI generates any business document (not index.md), it must first output the complete YAML metadata block (including 描述 and 标签), then write the body. If the document provided by the user lacks metadata, it should proactively complete it (including 描述 and 标签) and prompt the user for confirmation. Only when the user explicitly requests "minimal set only" should it degrade to only 6 fields.