企业官网建设流程全解析

1. 项目概述

1.1 为什么你需要一份“可更新”的AI工作手册

在这个AI浪潮里，几乎所有搞技术的人手头都攒了一堆学习资料：某大模型的开发文档、提示词模板、微调脚本、踩坑博客、会议笔记、收藏夹里几百条链接……资料越多越焦虑，因为真正用的时候根本找不到。

我自己就经历过这个阶段。电脑里十几个文件夹，命名混乱，docx、pdf、md、ipynb混杂，今天刚学的东西下周再翻就找不到了。直到后来意识到一个问题：零散资料不是资产，可检索、可沉淀、可迭代的工作手册才是资产。

这本手册不是教科书，不是文档仓库，更不是把网上的教程下载下来堆在一起。它的核心特征是：

• 围绕实际任务组织：以“我想解决什么问题”为中心，而不是“这篇教程叫什么名字”。
• 内容可版本化更新：AI领域技术迭代太快，手册必须能方便地增删改查。
• 面向检索和复用：写进去的每条内容都要便于搜索、便于套用。

这篇文章会从我的实际操作经验出发，讲清楚如何把一堆散落的AI学习资料整理成一份可持续更新的工作手册，包括整体设计思路、目录结构、具体流程、常见问题排查，以及一些容易被忽略的细节。

1.2 适合谁来参考

如果你是下面这几类人，我猜这篇内容对你会有用：

• AI产品经理或技术负责人：团队里AI相关资料满天飞，需要建立统一的知识沉淀方式。
• 算法工程师或研发工程师：手头有大量实验记录、论文笔记、代码片段，想整理成自己的个人知识库。
• 相关专业的学生：积攒了大量AI课程笔记和项目资料，需要一个结构化整理方案。
• 任何资料收藏爱好者：哪怕不搞AI，这套用Markdown+Git管理的思路也完全可以迁移到其他领域。

整个方案不依赖特定云服务或付费工具，核心就是一个文本编辑器加一个文件夹结构，后面的所有扩展都建立在简单的纯文本基础之上。这种选择本身就是刻意的：在AI知识管理这个更新换代飞快的领域，格式越简单，资料越长寿。

2. 整体设计与核心思路拆解

2.1 为什么选Markdown而非Word或在线文档

我说的Markdown是指那种纯文本、带标记语法、可以在本地用任意编辑器打开的文件格式。选择它有几个很实在的理由：

1. 纯文本长寿：十年后Word可能换了好几个版本，PDF的解析也可能出问题，但一个.md文件用记事本都能打开，内容永远不会被格式绑架。
2. 支持代码块：AI学习资料里最常出现的就是代码示例、API参数、命令行操作，Markdown的代码块语法让这些内容展示得清清楚楚。
3. 轻量易迁移：想从A工具换到B工具，直接复制粘贴文件夹就行，不需要任何转换。
4. 文本可检索：用系统自带的搜索也好、用第三方工具也好，纯文本的检索效率远高于富文本格式。
5. 方便版本管理：配合Git可以清楚看到每次修改了什么，谁改的，哪天改的。这一点在协作场景下特别重要。

至于在线文档，协作确实方便，但缺点是内容散落在云端，一旦时间久了账号丢失或者服务调整，整理的心血就全没了。我的做法是：以本地Markdown为数据源，必要时再导出成在线文档分享给别人，而不是反过来。

2.2 手册的定位：是执行工具，不是收藏夹

整理手册最怕的就是把它变成“第二个收藏夹”。很多人整理资料时的心态是“反正先存下来，以后再看”，结果存了十年也没看过。所以我在设计这套手册时，给自己定了一个原则：

手册里只记录两类内容：我实际要用到的、我实际踩过坑的。

这是整份手册的魂。有了这个定位，整理时就不会贪多。看到一个不错的教程，问自己一个问题：“这个内容我未来两周会不会用到？”如果答案是不会，那就别放进手册，顶多记一个链接到“参考资料索引”。只有实战验证过的方案、切实解决过问题的代码、踩过坑的排查记录，才值得占用手册的宝贵篇幅。

举例来说，一个“LangChain对话机器人笔记.md”可能存了十几种工具链的笔记，但真正写进手册的可能就是一个可运行的检索问答代码框架、三个踩过的版本兼容性坑、一份提示词调优表格。其他内容全部归入原始参考链接。

2.3 为什么版本管理是手册的重要基础

AI领域的痛点不是“资料少”，而是“资料更新太快”。你上个月记的API用法这个月就变了，上次调通的代码换个版本就报错。如果没有版本管理，你会面对一个没法回溯的困境：明明昨天还能跑，今天怎么就不行了？

用了Git之后，这个问题就变成了可以追溯的工程问题。比如某个方案突然失效，我可以直接git log看看上次改动前的内容，回溯整个变更历史，甚至可以git diff看看自己到底改了什么导致行为变化。这在调试AI模型的不可复现问题时尤其重要——很多“玄学”问题，最后就是通过变更回退定位到的。

版本管理还有一个额外的好处：同时维护多个分支，对应不同实验方向。比如主分支（main）放稳定可用的知识，其他分支放正在尝试的新方案，实验成熟后再合并。这样既不会污染主手册，又不会丢失探索过程中的经验。

2.4 目录结构的规划思路

手册的目录结构是整个体系的骨架，设计得不好后面全乱。我推荐一种基于“任务/主题混合”的目录结构，把AI学习的主要内容拆成几个大板块：

ai-handbook/ ├── README.md # 手册首页：总览、目录导航、最近更新记录 ├── docs/ # 核心知识内容，按主题划分 │ ├── basics/ # 基础概念与理论 │ ├── models/ # 模型原理与选型 │ ├── frameworks/ # 框架使用与踩坑 │ ├── prompts/ # 提示词工程 │ ├── training/ # 模型训练与微调 │ ├── deployment/ # 部署与推理优化 │ └── tools/ # 常用工具和脚本 ├── projects/ # 按项目组织的文档 │ ├── project-a/ # 以具体项目为单位沉淀内容 │ └── project-b/ ├── recipes/ # 可复用的“菜谱”：常见任务的详细步骤 ├── references/ # 外部链接索引、论文清单、资源聚合 ├── templates/ # 各类文档模板（新项目、方案评审、踩坑记录等） └── scripts/ # 辅助脚本：自动更新索引、目录生成等

这棵目录树看上去并不复杂，但每个分区的边界要清楚。比如docs/model/放的是“某个模型的学习笔记”，而recipes/放的是“用某个模型做某件事的完整操作步骤”，两者有本质区别。前者是知识，后者是操作手册。只是把一个别人的教程链接丢进docs/并不能帮助你解决问题，真正提高效率的是把问题解决过程沉淀成recipes/。

3. 核心细节解析与实操要点

3.1 文件命名规范：一眼认出是什么

文件命名看起来是个小事，但长期积累下来影响很大。我踩过不少坑：“文档1-最终版-真的最终版.md”、“新建文档2.md”这种命名方式在AI资料库中就是灾难。我最终采用的命名规范包含以下几个要素：

• 主题词：文件对应的核心概念或任务，比如llm-finetuning。
• 类型标识：是笔记（note）、方案（solution）、还是踩坑记录（troubleshoot）。
• 日期：按ISO格式写日期，方便按时间排序。

最终的文件名长这样：

llm-finetuning_note_20250412.md rag-solution_solution_20250410.md cuda-oom_troubleshoot_20250408.md

这里有个细节：日期用YYYYMMDD而不是YYYY-MM-DD，主要是为了让文件名在排序时按时间顺序排列，同时避免文件名中带的连字符和减号混淆。这个规范一旦定了就严格执行，哪怕觉得麻烦也要坚持，等到积累了几百个文件后你会感谢自己当初的这个决定。

每个文件开头还要加上一个标准化的元信息区，我用的是YAML格式，这样即使用普通文本工具打开也能一眼看到关键信息，同时还能被多种知识库工具识别：

--- type: note topic: llm-finetuning tags: [training, peft, lora] status: active create_date: 2025-04-12 update_date: 2025-04-20 ---

有了这些元信息，后续想按主题汇总、按状态筛选、按日期排序都很方便。

3.2 内容区块模板：强制的“三段式”

每一篇笔记不能是流水账，必须遵循一个统一的区块结构。我对所有内容卡了一个“三段式”框架：

• 背景（Context）：这个知识点是解决什么问题的？在什么场景下适用？
• 核心内容（Content）：这个知识点讲的是什么？原理、步骤、代码、参数，必须有操作层面的东西。
• 经验（Lessons）：我踩过的坑、验证过的参数、和其他方案的对比、后续需要注意的问题。

比如一篇关于LoRA微调的笔记，背景部分要写清楚“为什么选LoRA而不是全参数微调”，核心内容部分要把配置文件写出来、把训练命令写出来，经验部分要写清楚哪种任务下该调哪个参数、显存不够怎么降级。

这个鲜明确的结构有几个好处：

1. 写的人（你自己）知道该往哪里填内容，不用每次纠结“这篇该记什么”。
2. 读的人（未来的你）能快速定位，即使隔了三个月，也能直接跳到“经验”部分看重难点。
3. 方便自动汇总，之后可以写脚本扫描所有文件的元信息和标题，自动生成一个知识索引。

我特别想说的一点是：“经验”部分才是手册真正的价值所在。网上教程千篇一律，真正稀缺的是“我自己跑了这个方案之后得到的结果”。这可能只是一句“模型A在这个数据集上比模型B好5个百分点”，也可能是一句“这个API的batch参数跟文档描述完全不一致”，但正是这种东西构成了你跟别人的差距。

3.3 索引机制：让手册“活”起来

文件多了以后，最怕的就是“明明存过但找不到”。所以手册必须提供三个层次的索引机制：

• 总索引README.md：整个手册的总览，按板块列出常用条目和最近一周的更新记录。
• 标签索引：给每篇笔记打主题标签，用任意脚本扫描后可以生成“按标签聚合”的页面。
• 局部索引：在每个目录下放一个README.md，说明该目录存放什么内容、有什么高频入口。

我自己的做法是在scripts/目录下放一个build_index.py，扫描整个仓库的.md文件，提取元信息和一级标题，自动生成一份实时的INDEX.md。每次手动或通过Git钩子运行一次，手册的导航就始终是新的。

这里有个笨办法也很有效：每次学习新东西，在当天的笔记末尾，顺手加一行“相关链接”，把相关文档交叉引用一下。这一个动作带来的惊喜是：当你不确定某个问题该去哪看时，顺着“相关链接”串起来的路标，就能找到当初记录时的上下文。

3.4 工具选型：编辑器、Git仓库和自动化脚本

好的工具应该是“雕刻刀具”，不会让你把心思花在工具本身。我推荐的中心组合是：

• 编辑器：任何支持Markdown预览和目录树浏览的编辑器都行。比如VS Code、Obsidian、Typora都可以，关键在于你要习惯用纯文本编辑，而不是依赖某个专有格式。
• Git仓库：用Git管理整个目录，托管在本地或任意代码托管平台。Git是这些方案的地基，没有版本管理，整本手册最多算一个“看起来整齐的文件夹”。
• 脚本：用Python或Shell写一些辅助脚本，自动化索引更新、待办检查、文件归档等重复工作。

我自己的体验是：未必一开始就引入很重的知识库管理系统。越复杂的系统学习成本越高，等你花了一周时间整理结构、做配置、调试插件，结果正事一点没干。先用最朴素的Markdown+Git跑起来，等规模真的大了，再考虑引入更重的工具。而且Markdown作为通用格式，后期向任何工具迁移都很容易。

3.5 维护节奏：什么时候更新，什么时候删除

手册不是写好一次就完事了，它是一个需要定期喂养的生物。我给自己定的更新节奏包括：

• 学完一个新知识点，当天就记录：哪怕只写一个标题和几条要点，也比完全不写强。
• 解决一个实际问题，立刻沉淀：问题解决了，马上把排查过程和答案写进相应的部分。
• 每周花15分钟做索引整理：更新总README、检查过时内容、把处理完的草稿移到正式区。
• 定期清理：明确标为过时（status: deprecated）的条目，别直接删掉，而是归档。

关于删除，我的建议是用归档而非直接删除。Git虽然能恢复，但历史里找文件总归多一步。更好的做法是建一个archive/目录，把不适用于当前技术状态的旧文档移进去，标注好时间。这样整个主目录始终保持精简，而所有历史痕迹都不丢失。

4. 实操过程与核心环节实现

4.1 从一堆散乱资料到第一版手册：分阶段落地的步骤

我假定你现在的情况是：移动硬盘或网盘里已经有大量AI学习资料，但乱成一团。直接从零开始建一套理想目录肯定是痛苦的，不妨按下面的阶段过渡：

第一阶段（1天）：搭骨架

先建好目录结构，不必移动任何旧文件。只创建空目录和对应的README.md，并在总README.md里写上各板块的定位说明。空架子先立起来，后续往里填内容时自然会知道“新资料该往哪里放”。

第二阶段（3-7天）：从最新学的那个知识点开始填内容

不用追求把所有旧资料都整理完，那是永远做不完的。从你最近正在学的一个知识点或正在做的一个项目开始，把相关的内容抽出来按“三段式”写一篇标准笔记。写完你会发现，这种写法比单纯收集资料有用得多，因为它强迫你重新输出理解。有了第一篇，你自然会有动力整理下一篇。

第三阶段（持续）:边学边整理

把“新知识当天就按手册格式整理”变成一个习惯，让旧资料慢慢自然淘汰，新资料从一开始就进入正确的位置。旧资料里真正有价值的部分，会随着你不断翻阅而逐渐被搬到新结构里；而那些一直没被翻过的，说明根本没有沉淀价值，弃之也不可惜。

4.2 具体示例：把一篇“模型微调”笔记完整录入手册

下面以一个具体例子演示一篇笔记的完整落地过程。假设我要写一篇关于LoRA微调LLM的笔记，标题和结构如下：

--- type: note topic: training tags: [lora, peft, llm, finetune] status: active create_date: 2025-04-12 update_date: 2025-04-20 --- # LoRA微调LLM的最小可复现流程 ## 背景 为什么需要LoRA？全参微调一个7B模型需要约140GB显存（按每参数4字节估算），而LoRA只需要适配器参数。在单张24GB消费级显卡上也能微调。本文基于当时最新版的PEFT库，记录一套可复现的流程及经验。 ## 核心内容 ### 环境依赖 - Python 3.10以上 - PEFT 0.11.0以上版本 - Transformers 4.40.0以上版本 - 全精度训练时24GB显存大约只能支持7B模型LoRA+批次1；建议采用4比特量化可进一步降低显存门槛 ### 关键代码 ```python from peft import LoraConfig, get_peft_model, prepare_model_for_kbit_training model_id = "some-base-model" # 关键参数：rank、alpha、target_modules config = LoraConfig( r=8, lora_alpha=16, target_modules=[ "q_proj", "v_proj", "k_proj", "o_proj" ], lora_dropout=0.1, bias="none", task_type="CAUSAL_LM" ) model = prepare_model_for_kbit_training(base_model) model = get_peft_model(base_model, config)

训练配置要点

• 学习率：1e-4到2e-4之间，过低收敛慢，过高直接灾难性遗忘
• 批次大小：受显存限制，优先保证总batch size在合理范围，必要时用梯度累积
• 只训练适配器部分：打印可训练参数时，只有LoRA参数显示为可训练

经验与踩坑

• 绝对不要在target_modules里漏掉默认的query和value投影层，很多任务下漏掉会导致显著掉点
• PEFT库在0.10.0之后统一了API，老代码的LoraConfig(peft_type=...)写法已废弃
• 4比特量化加载模型时，要先调prepare_model_for_kbit_training可能比你预期的更影响训练稳定性
• 训练时Loss曲线正常但推理输出乱码，多半是分词器没有正确设置padding_side

可以看到，这篇笔记没有浪费一个字符在“什么是大模型”这种常识介绍上，干货密度很高。三个月后我翻回来看，通过标题和YAML元信息能够迅速定位；通过“背景”很快回忆起当初为什么写；通过“核心内容”可以直接照做一遍；通过“经验”避开了当初踩过的坑。 ### 4.3 自动生成索引的脚本示例 索引脚本帮助我把“随时的维护成本”降到最低。下面是一个极简版本，只做三件事：扫描所有Markdown文件、提取YAML元信息和一级标题、生成`INDEX.md`。 ```python #!/usr/bin/env python3 import os import re from pathlib import Path from datetime import datetime ROOT = Path(__file__).parent.parent def parse_front_matter(text: str): if not text.startswith("---"): return {} end = text.find("---", 3) if end == -1: return {} yaml_block = text[3:end] fields = {} for line in yaml_block.strip().splitlines(): if ":" in line: key, value = line.split(":", 1) fields[key.strip()] = value.strip() return fields def extract_title(text: str): match = re.search(r"^# (.+)$", text, re.MULTILINE) return match.group(1).strip() if match else "未命名" def main(): entries = [] for md_file in sorted(ROOT.rglob("*.md")): if md_file.name == "INDEX.md" or "archive" in md_file.parts: continue text = md_file.read_text(encoding="utf-8") fm = parse_front_matter(text) title = extract_title(text) rel_path = md_file.relative_to(ROOT).as_posix() tags = fm.get("tags", "") status = fm.get("status", "active") update_date = fm.get("update_date", "未知") entries.append((update_date, rel_path, title, tags, status)) lines = [ "# 手册索引", "", f"> 自动生成时间：{datetime.now().strftime('%Y-%m-%d %H:%M')}，请勿手工编辑。", "", "## 全部条目", "", "| 最后更新 | 文件 | 标题 | 标签 | 状态 |", "| --- | --- | --- | --- | --- |", ] for update_date, rel_path, title, tags, status in sorted(entries, reverse=True): lines.append(f"| {update_date} | [{rel_path}]({rel_path}) | {title} | {tags} | {status} |") (ROOT / "INDEX.md").write_text("\n".join(lines), encoding="utf-8") print(f"生成索引完成，共{len(entries)}个文件。") if __name__ == "__main__": main()

这个脚本完全可以放在scripts/目录下，每次更新完笔记后执行一次。你也可以在Git的pre-commit钩子加上一行，让它自动在你提交前更新索引。需要注意的是，脚本不会去解析真正的YAML库，只是用最原始的字符串截取，因此所有元信息必须严格遵循第一行的---格式，否则解析会出问题。

4.4 用Git管理手册的实用配置

为了让Git真正成为手册的好搭档，有几个配置值得做。

首先养成写清晰提交信息的习惯。我的提交信息格式：前缀+简述，例如：

git add docs/prompts/agent-prompt-template_solution_20250420.md git commit -m "docs(prompts): 补充Agent系统提示词模板及测试结果"

前缀主要用feat（新增内容）、fix（修正错误）、docs（文档调整）、refactor（结构重排）。格式不一定严格遵循某个规范，但信息本身的含义要清楚：别人（或者未来的你）看一眼提交信息，就知道这次更新干了什么。

其次，建议给关键节点打上Tag。有些知识受过实战检验，有些还只是探索性的笔记，用Git Tag区分“已验证”和“实验性”内容是很实用的做法。比如：

git tag -a v1.0 -m "手册结构稳定，基础概念部分完成，已验证LoRA微调流程"

第三，可以设置.gitignore忽略临时文件，防止各种编辑器的临时文件污染仓库。比如忽略.DS_Store、*.tmp、*.bak等。

最后，如果协作，考虑把仓库托管到一个私有代码托管服务，但内容过于敏感或有合规考虑时，则保持纯本地也可以。多个设备同步可以用自建的同步盘或者Git远端，这个按你的偏好来。

5. 常见问题与排查技巧实录

5.1 手册越写越乱，该从哪里重新下手

很多人整理到一半会陷入“螺旋混乱”：目录定了又改，文件挪来挪去，最后比不整理还乱。这时候我的建议是：先停下来，别整理存量，从新增量开始。

把现在的目录结构打印出来，站在“如果三天后我要找一个东西，我会先点开哪个目录”的角度审视一遍。如果每个目录的定位你都能一句话说清楚，说明结构没问题，乱的是具体文件，那就把文件挪到正确位置。如果某个目录你自己都说不清是干嘛的，说明这个目录本身就是多余的，合并或删除。

另一个有效的方法是建立“临时收集区”（inbox）：任何不确定放到哪里的新资料，先扔进inbox/目录，每周花五分钟整理一次。这个小技巧看着不起眼，却能极大程度避免“因为不知道该放哪，所以干脆不存了”的尴尬。文档最忌讳的就是存的时候纠结，所以宁可先放在临时区，也绝不能放任资料丢失。

5.2 同步冲突和版本回退的常见情况

如果笔记本和台式机同时工作，或者几个人协作，Git冲突在所难免。最典型的场景是：你在一台设备上提交了更新，另一台设备也基于旧版本做了修改，推送时就出现冲突。

我的处理方法是：每次开始工作前先拉取最新内容，改完后尽快提交推送，避免长期保留本地和远端的分叉。如果冲突真的出现了，那就按冲突标记逐个处理。这里的关键是，不要用git checkout .等暴力指令放弃本地改动，除非你确认那些改动确实不需要了。先git stash暂存本地的修改，处理完冲突后再git stash pop，通常更稳妥。

另外强烈建议不要在手机上直接编辑Git仓库里的Markdown文件。手机编辑容易引入奇怪的编码问题、误触回车的换行符混乱，防不胜防。手机端只做“查看”或“转发”，真正的编辑回到电脑上。

5.3 资料内容过时了怎么办

AI技术更新太快，去年能跑的训练流程今年就报错，这是常态。我的策略是：

• 不直接删内容，而是把状态标记改为deprecated，并写一行“废弃原因”和“替代方案”。
• 如果某个内容被新内容完全取代，就移动到archive/目录下，保留可追溯性。
• 内容和代码尽量写“验证时间”和“当时版本”，这样即使半年后发现不适用，也能快速定位是哪次升级导致的。

这个习惯不会让你的手册永远正确，但会让它“知道自己在什么时候是正确的”。在AI领域，“有时间戳的正确”才是真的正确。官方文档也在不断更新，你基于某个版本记录的操作步骤，只有带上版本号才有复现的价值。

5.4 提效小技巧：模板文件直接复用

在templates/目录下维护几个模板，能显著降低每次从零开始写文档的阻力。常用的模板包括：

• 笔记模板（note）：背景+核心内容+经验三段式。
• 踩坑记录模板（troubleshoot）：问题现象、排查过程、根因分析、解决方案、预防措施。
• 方案设计模板（solution）：需求背景、方案对比、选型理由、实施步骤、验证方式。
• 项目总结模板（project-summary）：项目目标、时间线、关键决策、最终效果、可复用资产。

每次新建文件时，直接复制对应模板，填内容就好。这个动作大大减少了“打开空白文档不知道从哪开始写”的拖延症。

说到模板，我也顺手放一个踩坑记录模板的片段供参考：

--- type: troubleshoot topic: deployment tags: [llm, memory, cuda] status: active create_date: 2025-04-18 update_date: 2025-04-18 --- # CUDA显存不足（CUDA OOM）排查记录 ## 现象 启动推理脚本时报错：CUDA out of memory. ## 排查过程 - 用`nvidia-smi -l 1`监控显存占用曲线，发现模型加载后就占用了超过80%现存 - 怀疑是batch size太大，从8调低到1，问题依旧 - 检查代码后发现`max_length`被设置为2048，且同时为每句话做了padding，导致实际分配显存远超预期 - 进一步排查发现tokenizer没有设置`padding=True`，批量推理时长短不一却统一padding到2048 ## 根因 没有对输入序列做动态padding，且没有设置`truncation`参数。 ## 解决方案 在tokenizer调用时设置`padding=True, truncation=True, max_length=512`，利用DataLoader的`collate_fn`统一padding到当前batch的最大长度，而不是全局最大长度。 ## 预防措施 - 所有推理脚本模板中默认开启动态padding - 代码评审时检查tokenizer参数

有了模板，你不用每次重新想“该记录什么”，只需要把实际现象和解决过程填进去即可。这种“格式化的力量”在整理知识时真的很重要。

6. 个人经验与优化建议

6.1 这套方法的适用范围边界

说了这么多优点，也得说说边界。这套基于Markdown+Git的方案，最适合个人或小团队使用。如果你的公司有严格的合规要求，或者文档需要在几百人之间协同编辑，那可能需要更重型的知识管理系统。但即便是那种情况，我仍然建议在初期用轻量方案把内容整理一遍，等真正成规模后再迁移。因为迁移的只是纯文本文件，成本极低，而你在“轻量阶段”沉淀下来的内容结构本身就是最宝贵的资产。

另外，如果资料中包含敏感数据、客户信息、内部代码，务必注意保管方式。本地文件该加密的加密，远端仓库该私有的私有。内容安全是底线问题，不要因为图方便而忽视。

6.2 我踩过的几个关键坑

整理AI学习资料这件事，我自己试错了不少次。有几个坑如果你能避开，能省下大把时间：

• 过度设计目录结构。一开始就设计了二十个目录、几十个标签，结果发现维护成本极高，很多文件放哪个目录都能说得通，最后为了分类标准浪费了大量时间。简单结构起步，随实际需求演进，永远比“一次性设计到位”靠谱。
• 追求一次整理完所有历史资料。这是最大的心结。事实上旧资料里90%以上再也不会被打开，为了万无一失把它们挨个归类纯粹是心理安慰。真正要做的是：按需整理，用到哪个就整理哪个。
• 工具迷恋。经常在“用什么软件管理知识”上反复折腾，Obsidian、Notion、印象笔记换了一圈，最后发现文件内容才是核心。工具只是外壳，别把时间花在磨刀上不砍柴。
• 忘了写“为什么”。只记录了步骤，没记录当时的背景和决策原因。几个月后回看，往往只记得“当时这样做了”，却忘了“为什么非这样做不可”。在工作手册里，“为什么”往往比“怎么做”更值钱。

6.3 后续扩展方向

这套手册体系稳定后，还可以往几个方向扩展：可以增加自动化测试脚本，定期检查笔记里的代码是否符合当前库版本；可以加入更多可复用的“决策日志”，记录每个技术选型背后的对比和取舍；也可以把模板接到团队协作流程中，让新成员通过手册快速入门。但无论怎么扩展，核心始终是那条朴素的原则：内容组织服务于实际落地，而不是服务于“看起来整齐”。

最后再分享一个小技巧

每次写完一篇新笔记，花十秒钟在笔记最顶上更新一下日期，并且在总README的“最近更新”区域追加一行。这个看似多余的动作，会让整本手册始终保持一种“活”的状态。等你回看整本手册时，你会通过这条时间线看到自己在AI学习路上的成长轨迹——这本身也是持续整理下去的最大动力。