第 4 篇：内容即数据——frontmatter 规范、数据结构与构建链路的工程化设计
📌 本篇核心目标：建立"内容文件不是文本，而是系统输入"的工程化思维。掌握 frontmatter 字段设计方法论、slug 规则、分类标签治理策略、核心实体的 schema 设计，以及从内容到页面的完整构建链路。
这篇为什么是整本小册最重要的一篇
前三篇教你搭了两层东西：
第 2 篇：CLAUDE.md 主文件（规则入口）
第 3 篇：docs/ 文档体系（专项细则）
但如果这些文档里的内容质量不高——规则写得不准、字段设计有漏洞、数据链路没理清——那整套体系就是个空架子。
这篇讲的是"往架子里填什么"。
具体来说，它回答三个问题：
内容文件的 frontmatter 应该怎么设计，才能稳定、可维护、不被 Claude 搞乱？
项目的数据实体和字段关系应该怎么梳理，才能在结构变更时有据可查？
从 content/ 目录到最终页面的构建链路是什么样的，Claude 需要理解到什么程度？
这三个问题的答案，直接决定了你的 docs/content-rules.md、docs/data-schema.md 和 docs/build-process.md 写得好不好。
也直接决定了 Claude 在你的内容项目中犯错频率是高还是低。
第一个认知转变：内容文件不是文本
你打开content/articles/teacher-cert-guide.md，看到的是这样的东西：
--- title: 2026年教师资格证报考完整指南 description: 从报名条件到考试科目，一文搞懂教资报考全流程 slug: teacher-cert-guide category: 备考指南 tags: [教师资格证, 报考流程, 2026] date: 2026-01-15 draft: false --- # 2026年教师资格证报考完整指南 教师资格证考试是……看起来就是一篇 Markdown 文章，对吧？
但从系统的角度看，它同时是 8 个东西：
这篇 Markdown 文件，同时是： 1. 详情页的数据源 → title、description、content 被渲染成详情页 2. 列表页的一个条目 → title、description、date 出现在文章列表里 3. 分类聚合页的成员 → category="备考指南" 让它出现在"备考指南"分类页 4. 标签聚合页的成员 → tags 让它出现在"教师资格证"等标签页 5. 搜索索引的一条记录 → title、description、tags、content 被写入搜索数据 6. 路由系统的一个映射 → slug="teacher-cert-guide" 决定 URL 是 /teacher-cert-guide 7. SEO 的元数据来源 → title 和 description 影响搜索引擎收录 8. 内链和推荐的被引用对象 → 其他文章的 related_articles 可能引用它的 slugClaude 默认不知道这些。
它看到一个 Markdown 文件，只会把它当"一篇文本"来处理。你让它"改个分类"，它就改了——不会想到这个改动还影响分类聚合页。你让它"优化一下 slug"，它就改了——不会想到旧 URL 会 404、搜索引擎已收录的链接会失效。
你的 docs/content-rules.md、docs/data-schema.md 和 docs/build-process.md 的核心任务，就是把这些"隐性连锁关系"变成"Claude 能看到的显性规则"。
下面一个模块一个模块来讲。
Frontmatter 设计方法论
Frontmatter 是内容文件的"头部元数据"，是整个内容系统的数据基础。它设计得好不好，直接决定了你的内容系统是"越用越稳"还是"越用越乱"。
设计原则：稳定性 > 完整性
很多人设计 frontmatter 的思路是"我需要什么字段就加什么字段"。结果三个月后，不同时期新增的内容文件，frontmatter 五花八门——有的有summary，有的没有；有的用author，有的用writer；有的tags是数组，有的是逗号分隔的字符串。
正确的设计思路是：先定一套稳定的基础字段，所有内容文件严格遵守。扩展字段只在确认被消费后才启用。
"稳定"的意思是：
字段名不变
字段类型不变
字段语义不变
是否必填不变
一旦某个字段进入了"基础字段"清单，就不要轻易改动它。因为改动一个基础字段，意味着你需要同时更新：所有内容文件、类型定义、解析函数、页面模板、搜索索引脚本——任何一个环节遗漏，都会出问题。
基础字段：你必须有的 7 个
不管你的项目多大多小，以下 7 个字段基本是内容型知识库项目的标配：
--- title:"" # 页面标题 description:"" # 内容摘要 slug:"" # 唯一访问标识 category:"" # 主分类 tags:[] # 标签数组 date:"" # 发布时间 draft:false # 是否草稿 ---逐个说明为什么这 7 个是必备的：
title
最基础的字段，没什么争议。用于详情页标题、列表页展示、SEO 标题、搜索索引。
唯一需要注意的是：title 是"给人看的标题"，不是文件名。文件名用 slug 风格（小写英文+中划线），title 用自然语言。
description
内容摘要。用于列表页卡片、SEO meta description、搜索结果的展示片段。
很多人在早期会省略这个字段，结果列表页的摘要显示要么是空的，要么是用正文前 100 字截取的——效果很差。
建议：description 设为必填，长度控制在 50-150 字之间。
slug
整个 frontmatter 中最关键的字段，没有之一。它决定了页面的 URL，是内容在整个系统中的"身份证"。
后面会专门用一整节来讲 slug 规则。
category
主分类。每篇内容只属于一个 category。用于导航、分类聚合页、侧边栏分组。
category 和 tags 的区别后面会详细讲。
tags
标签数组。用于横向关联、搜索过滤、相关推荐。
注意 tags 必须是数组格式（tags: [标签A, 标签B]），不要用逗号分隔的字符串。统一格式能避免解析问题。
date
发布时间。用于排序、时间线展示、"最新内容"功能。
格式建议统一为YYYY-MM-DD。不要有的文件用2026-01-15，有的用2026/01/15，有的用Jan 15, 2026。格式不一致会导致排序出错。
draft
是否为草稿。draft: true的内容不应该出现在正式的列表页、搜索索引和聚合页中。
这个字段看起来简单，但它的影响范围很大——构建脚本、搜索索引、列表查询、RSS 生成，所有环节都需要正确过滤草稿。一旦过滤逻辑有漏洞，草稿内容就会被公开发布。