名称: 蓝图组织 用户可调用: 假 描述: 当管理蓝图目录结构和避免重复时使用。始终在创建前搜索现有蓝图以防止重复文档。处理命名约定和交叉引用。 允许工具: [读取, 写入, 编辑, Grep, Glob]
组织技术蓝图
目录结构
blueprints/
├── README.md # 索引和概述
├── {系统名称}.md # 每个系统一个文件
├── {功能名称}.md # 每个功能一个文件
└── {集成名称}.md # 每个集成一个文件
扁平化与嵌套化
优先使用扁平化结构 对于大多数项目：
- 更容易导航
- 交叉引用更简单
- 组织开销更少
仅用于大型项目时才使用子目录：
blueprints/
├── README.md
├── 核心/
│ ├── README.md
│ └── *.md
├── 功能/
│ └── *.md
└── 集成/
└── *.md
命名约定
文件名
- 使用短横线分隔式：
用户认证.md - 匹配代码中的系统/功能名称
- 要具体：
API速率限制.md而不是API.md - 避免通用名称：
工具.md,助手.md
好名称示例
MCP服务器.md- 具体系统设置合并.md- 具体功能GitHub集成.md- 具体集成
坏名称示例
概述.md- 太通用（使用README.md）杂项.md- 万能杂烩是反模式新功能.md- 不具描述性
blueprints/README.md 索引
每个blueprints/目录都需要一个索引：
# 技术蓝图
为{项目名称}提供的实现文档。
## 概述
项目简要描述及其蓝图组织方式。
## 系统
核心系统及其文档：
### 核心
- [设置管理](./设置管理.md) - 如何加载和合并配置
- [插件系统](./插件系统.md) - 插件发现和加载
### 功能
- [MCP服务器](./MCP服务器.md) - 模型上下文协议实现
- [钩子分发](./钩子分发.md) - 如何执行钩子
### 集成
- [GitHub集成](./GitHub集成.md) - GitHub API集成
## 贡献
添加新蓝图时：
1. 检查现有相关文档
2. 使用一致的命名和结构
3. 更新此索引
避免重复
重复问题
重复文档：
- 失去同步
- 混淆读者
- 浪费维护精力
预防策略
-
创建前搜索 使用原生工具
# 列出所有现有蓝图 Glob("blueprints/*.md") # 搜索提及主题的蓝图 Grep("auth", path: "blueprints/", output_mode: "files_with_matches") # 读取特定蓝图检查覆盖范围 Read("blueprints/认证.md") -
单一真相源
- 每个概念仅记录一次
- 其他位置链接到源
-
合并相关主题
- 组合紧密耦合的系统
- 仅在真正独立时才拆分
-
广泛交叉引用
有关认证细节，请参见[用户认证](./用户认证.md)。
拆分与合并的判断
合并时：
- 系统紧密耦合
- 理解一个需要理解另一个
- 它们共享大量上下文
拆分时：
- 系统可以独立理解
- 不同受众需要不同文档
- 文件将超过约500行
处理重叠
当系统重叠时：
选项1：主要位置 + 引用
在一个地方记录，从其他位置引用：
# 系统A
## 认证
该系统使用共享认证。详见[认证](./认证.md)。
选项2：共享部分
创建一个共享蓝图供两者引用：
# 系统A
使用[共享认证](./共享认证.md)
# 系统B
使用[共享认证](./共享认证.md)
# 共享认证
细节在此...
选项3：范围化内联
在每个中记录重叠，但限于该系统范围：
# 系统A
## 认证（系统A特定）
系统A如何使用认证的特定方式...
弃用
当系统被移除时：
- 删除蓝图文件 - 不要“为历史保留”
- 更新索引 - 从README.md中移除
- 修复损坏链接 - 更新任何引用
- Git历史 - 使用版本控制记录历史
审计组织
定期检查：
- [ ] 所有蓝图文件在索引中？
- [ ] 所有索引条目都有文件？
- [ ] 没有明显重复？
- [ ] 名称匹配代码术语？
- [ ] 交叉引用有效？
- [ ] 没有孤立文件？
工具
查找孤立蓝图
# 不在README.md中的文件
for f in blueprints/*.md; do
grep -q "$(basename $f)" blueprints/README.md || echo "孤立: $f"
done
查找重复主题
# 类似文件名
ls blueprints/*.md | xargs -n1 basename | sort | uniq -d
# 类似内容
grep -l "特定术语" blueprints/*.md