AI 技术知识库结构设计（主题目录 + 子主题文件）

• 状态：已验证
• 来源：对话整理
• 更新时间：2026-03-12

关键结论

• 技术知识库更适合采用“主题目录 + 子主题文件”的中粒度结构。
• 主题目录用于分类，子主题文件用于承载一类强相关知识，而不是一句结论一个文件。
• 应避免使用单一巨型入口文件承载整个主题的所有内容。
• 也不应机械拆成“一个极小知识点一个文件”，否则会导致文件数量失控、查找困难。

详细分析

• 单一主题文件会随着时间增长到数千行，后续维护、检索和审阅都会明显变差。
• 当多个知识点持续写入同一文件时，git diff 会更混乱，也更容易出现更新冲突。
• 如果继续细分到“一个极小知识点一个文件”，又会造成目录过碎，导航和查找成本明显上升。
• 更稳妥的方案是按主题建立目录，再按子主题或知识域拆分文件，在可维护性和可检索性之间取得平衡。

可执行步骤

1. 修改 AGENTS.md 中关于主题文档组织方式的规则。
2. 将内容增长过快的主题入口文件逐步迁移为 topics/<topic>/ 目录 + 子主题文件结构。
3. 以子主题或知识域为单位创建 Markdown 文件，而不是为每条零碎结论单独建文件。
4. 后续 AI 写入文档时，优先更新对应子主题文件。

命令 / 配置 / 代码

ai-notes/
├── README.md
├── INDEX.md
└── topics/
    ├── git/
    │   ├── overview.md
    │   ├── worktree.md
    │   ├── submodule.md
    │   └── bundle.md
    ├── linux/
    │   ├── overview.md
    │   ├── ssh.md
    │   └── systemd.md
    └── networking/
        ├── overview.md
        ├── frp.md
        └── stun.md

文件命名规则：kebab-case

风险与注意事项

• 不要把所有知识持续写入单个主题文件。
• 目录层级不宜过深，否则检索和导航成本会上升。
• 不要把每个很小的知识点都拆成独立文件，否则会重新降低可检索性。
• 每个子主题文件应保持单一知识域，避免重新演变成杂项文档。