docs(claude): restructure documentation management and add feedback system
- Restructure §8 from "文档沉淀规则" to "文档管理规则" with 4 subsections - Add docs/ structure with features/ and knowledge-base/ directories - Add feature documentation template with 7 sections (概述/设计初衷/技术设计/预期作用/实际效果/演化路线/头脑风暴) - Add feature update trigger matrix (新增/修改/完成/问题/反馈) - Add documentation quality checklist - Add §16
This commit is contained in:
80
CLAUDE.md
80
CLAUDE.md
@@ -282,9 +282,63 @@ pnpm tsc --noEmit
|
||||
|
||||
---
|
||||
|
||||
## 8. 文档沉淀规则
|
||||
## 8. 文档管理规则
|
||||
|
||||
凡是出现以下情况,应更新 `docs/openfang-knowledge-base.md` 或相关文档:
|
||||
### 8.1 文档结构
|
||||
|
||||
```text
|
||||
docs/
|
||||
├── features/ # 功能全景文档
|
||||
│ ├── README.md # 功能索引和优先级矩阵
|
||||
│ ├── brainstorming-notes.md # 头脑风暴记录
|
||||
│ ├── 00-architecture/ # 架构层功能
|
||||
│ ├── 01-core-features/ # 核心功能
|
||||
│ ├── 02-intelligence-layer/ # 智能层 (L4 自演化)
|
||||
│ ├── 03-context-database/ # 上下文数据库
|
||||
│ ├── 04-skills-ecosystem/ # Skills 生态
|
||||
│ ├── 05-hands-system/ # Hands 系统
|
||||
│ └── 06-tauri-backend/ # Tauri 后端
|
||||
├── knowledge-base/ # 技术知识库
|
||||
│ ├── openfang-technical-reference.md
|
||||
│ ├── openfang-websocket-protocol.md
|
||||
│ └── troubleshooting.md
|
||||
└── WORK_SUMMARY_*.md # 工作日志
|
||||
```
|
||||
|
||||
### 8.2 功能文档维护规范
|
||||
|
||||
**何时更新功能文档**:
|
||||
|
||||
| 触发条件 | 更新内容 |
|
||||
|---------|---------|
|
||||
| 新增功能 | 创建新文档,填写设计初衷 |
|
||||
| 功能修改 | 更新技术设计、预期作用 |
|
||||
| 功能完成 | 更新实际效果、测试覆盖 |
|
||||
| 发现问题 | 更新已知问题、风险挑战 |
|
||||
| 用户反馈 | 更新用户反馈、演化路线 |
|
||||
|
||||
**功能文档模板**:
|
||||
|
||||
```markdown
|
||||
# [功能名称]
|
||||
|
||||
> **分类**: [架构层/核心功能/智能层/上下文数据库/Skills/Hands/Tauri]
|
||||
> **优先级**: [P0-决定性 / P1-重要 / P2-增强]
|
||||
> **成熟度**: [L0-概念 / L1-原型 / L2-可用 / L3-成熟 / L4-生产]
|
||||
> **最后更新**: YYYY-MM-DD
|
||||
|
||||
## 一、功能概述
|
||||
## 二、设计初衷(问题背景、设计目标、竞品参考、设计约束)
|
||||
## 三、技术设计(核心接口、数据流、状态管理)
|
||||
## 四、预期作用(用户价值、系统价值、成功指标)
|
||||
## 五、实际效果(已实现、测试覆盖、已知问题、用户反馈)
|
||||
## 六、演化路线(短期/中期/长期)
|
||||
## 七、头脑风暴笔记(待讨论问题、创意想法、风险挑战)
|
||||
```
|
||||
|
||||
### 8.3 知识库更新规则
|
||||
|
||||
凡是出现以下情况,应更新 `docs/knowledge-base/` 或相关文档:
|
||||
|
||||
- 新的协议坑 (REST/WebSocket)
|
||||
- 新的握手/配置/模型排障结论
|
||||
@@ -294,6 +348,16 @@ pnpm tsc --noEmit
|
||||
|
||||
原则:**修完就记,避免二次踩坑。**
|
||||
|
||||
### 8.4 文档质量检查清单
|
||||
|
||||
每次更新文档后,检查:
|
||||
|
||||
- [ ] 文件路径引用正确
|
||||
- [ ] 技术术语统一
|
||||
- [ ] ICE 评分已更新
|
||||
- [ ] 成熟度等级已更新
|
||||
- [ ] 已知问题列表已更新
|
||||
|
||||
---
|
||||
|
||||
## 9. 常见高风险点
|
||||
@@ -407,3 +471,15 @@ docs(knowledge-base): capture OpenFang RBAC permission issues
|
||||
- [ ] 插件从 TypeScript 改为 SKILL.md
|
||||
- [ ] 添加 Hands/Workflow 相关 UI
|
||||
- [ ] 处理 16 层安全防护的交互
|
||||
|
||||
---
|
||||
|
||||
## 16. 参考文档更新
|
||||
|
||||
- `docs/features/README.md` - 功能索引和优先级矩阵
|
||||
- `docs/features/brainstorming-notes.md` - 头脑风暴记录
|
||||
- `docs/knowledge-base/openfang-technical-reference.md` - OpenFang 技术参考
|
||||
- `docs/knowledge-base/openfang-websocket-protocol.md` - WebSocket 协议
|
||||
- `docs/knowledge-base/troubleshooting.md` - 排障指南
|
||||
- `skills/` - SKILL.md 技能定义
|
||||
- `hands/` - HAND.toml 自主能力包
|
||||
|
||||
Reference in New Issue
Block a user