feat: 配置 AI Coding 项目管理系统(方案 B)
Deploy Wiki to Production / deploy (push) Has been cancelled

- 新增 KANBAN.md 项目看板(待办/进行中/已完成/问题/定期维护)
- 新增 specs/ 需求规格目录
- 新增 sessions/ AI 编码会话沉淀目录
- 新增 prompts/ 已验证 Prompt 模板目录
- 更新 CLAUDE.md 增加项目管理工作流章节
This commit is contained in:
zdh
2026-06-20 22:32:32 +08:00
parent 1b1b503eee
commit 12740c13b1
6 changed files with 325 additions and 13 deletions
+95 -13
View File
@@ -10,17 +10,28 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
## 版本控制
`招标投标AI推广应用政策解读/` 子目录有独立的 `.git/`。部署通过 `/remote-sync`rsync)完成,不走 git push 流程
代码托管在 **Gitea 私服**(非 GitHub),`.gitea/workflows/deploy.yml` 在 push 到 `main` 分支时自动 rsync 到 `/data/wiki/` 并 reload nginx
`.gitignore` 排除了 `.superpowers/``qModel/.git/` 以及嵌套子目录的独立 `.git/`
`招标投标AI推广应用政策解读/` 子目录有独立的 `.git/`。手动部署也可通过 `/remote-sync` 调用 rsync 到 `39.100.114.100:/data`
`.gitignore` 排除了 `.superpowers/``qModel/.git/`、嵌套子目录的独立 `.git/``**/logs/``.claude/skills/ui-ux-pro-max/`
### 部署排除
`.gitea/workflows/deploy.yml` 在 rsync 到生产环境时排除以下内容:
- `.claude/``.gitea/``.gitignore``CLAUDE.md` — 开发工具与配置
- `*.pptx``*.xlsx` — 源材料/二进制文件
- `.git/` — 版本控制元数据
> ⚠️ **安全提醒**`.claude/skills/remote-sync/SKILL.md` 包含硬编码 SSH 凭证,该文件不会被部署到生产环境,但存在于 git 仓库中。如需公开此仓库,应先清理凭证。
## 目录约定
每个子目录遵循 `{主题}/{类型}/` 的层级结构,类型包括 `报告/``代码/``笔记/` 等。新增主题目录时保持此约定。
**例外情况**
- `crmeb-mer-graph-report.html`位于根目录的单文件报告,不走子目录结构
- `mcp-services-guide/` — 有独立 `index.html`自成一体子站,不遵循 `报告/` 子目录模式
- `AI核心技能原理说明.html``crmeb-mer-graph-report.html``szihl-soe-reform-report.html``张德海_简历.html` — 根目录的单文件报告/简历,不走子目录结构
- `mcp-services-guide/``深国际综合改革方案/` — 有独立 `index.html`自成一体子站,不遵循 `报告/` 子目录模式
- `交互式演示/` — 存放交互式前端 demo(如正四面体 3D 动画),非报告页
- `中医馆内部管理系统/报告/` 下有 `.md` 需求文档,是唯一在 `报告/` 目录下出现非 HTML 文件的情况(其他 `.md` 文件如 `研发型企业AI转型方案/section-*.md``政府审批流解决方案/*.md``YqBoot系统说明书/*.md` 位于主题根目录,属规划/源文件,不走报告页模板)
- `研发型企业AI转型方案/``.md` 分段规划文件 + `.pptx`/`.xlsx` 源材料位于主题根目录,HTML 报告在 `报告/` 子目录
@@ -54,10 +65,11 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
**新增文档**:在对应分类的 `items` 数组中添加条目。如果分类不存在,新建一个分类对象。
**颜色映射**`wikiData``color` 字段的语义约定,颜色值直接写在各分类条目中):
- `pink` — 深度分析、政策解读、政务行业
- `pink` — 深度分析、政策解读、政务行业、企业AI转型
- `blue` — 工程指南、数据平台、医疗健康
- `mint` — 调研研究、商业分析、配送到家
- `lavender` — 参考资源、AI 工具、关于作者
- `orange` — 抖音话题、短视频脚本
新增分类时选择语义匹配的颜色,颜色样式通过 `card-badge` 类渲染。
@@ -65,7 +77,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
- 侧栏导航(桌面端)+ 抽屉导航(移动端 ≤768px)
- 实时搜索(按标题、描述、分类名匹配)
- 暗色/亮色模式切换(localStorage 持久化
- 暗色/亮色模式切换(优先级:localStorage `wiki-theme``prefers-color-scheme: dark` 系统偏好 → light 默认
- 响应式布局:≤768px 隐藏侧栏,显示移动端 chip 筛选栏
### JS 运行时架构
@@ -84,8 +96,8 @@ wikiData (声明式) → allItems (展开数组, 附加 section/icon) → 视图
| `searchQuery` | 搜索框绑定值,实时过滤 |
| `render()` | 分发函数:`currentView === 'all'` 时调用 `renderAllView(main)`,否则 `renderSectionView(main)` |
| `buildNav(targetEl)` | 构建侧栏/抽屉导航 HTML,绑定点击事件切换视图 |
| `buildChips()` | 构建移动端 chip 筛选栏 |
| `setTheme(t)` | 主题切换:设置 `data-theme` 属性 + localStorage 键 `wiki-theme`,同时尊重 `prefers-color-scheme: dark` 系统偏好 |
| `buildChips()` | 构建移动端 chip 横向滚动筛选栏(分类 pill 按钮),点击切换 `currentView` |
| `setTheme(t)` | 主题切换:`document.documentElement.setAttribute('data-theme', t)` + `localStorage.setItem('wiki-theme', t)`。初始化优先级见「页面特性」 |
## 报告页模板
@@ -96,20 +108,39 @@ wikiData (声明式) → allItems (展开数组, 附加 section/icon) → 视图
4. Markdown 内容通过内联 HTML 渲染(表格、代码块、列表)
5. 语言属性 `lang="zh-CN"`
创建新报告页时,复制任意现有报告页的 `:root` 和 header 结构作为模板。
创建新报告页时,复制任意现有报告页的 `:root` 和 header 结构作为模板。**推荐使用物流网系列报告页**(如 `市属国企参与物流网建设调研报告/报告/`)作为模板,它们有最完整的侧栏目录实现。
> **关键模式**:报告页是独立打开的 HTML 文件(非 iframe 嵌入),每个页面必须在自己的 `<style>` 标签内定义完整的 `:root` CSS 变量块。不从 `index.html` 继承样式,变量块不可省略。
**报告页有两种变体**
1. **基础版**(大多数报告):固定 header-bar + 单列内容区,结构最简单
2. **侧栏导航版**(物流网系列报告):左侧 260px 粘性导航菜单 + 右侧内容区,适合多章节长报告。标题带 `[章节名]` 便于搜索跳转
**🔴 每页必有**`← 返回知识库` 链接 — 所有页面(含报告页、特殊布局页、简历页)顶部必须有此导航链接。路径规则:根级文件 `./index.html`,一级子目录 `../index.html`,二级子目录 `../../index.html`
移动端(≤768px)侧栏导航版自动隐藏菜单,显示汉堡按钮触发抽屉导航。
**手机适配版**:部分报告有 `_mobile.html` 后缀的独立手机版(卡片式折叠布局 + 底部标签导航),如 `中医馆内部管理系统_需求分析对比报告_mobile.html`
### 页面分类与样式差异
并非所有报告页都使用 Fluent 2 标准 Token。部分页面使用独立的色彩体系(详见 `.claude/design-tokens.md` §15.2):
| 类别 | 特征 | 布局要求 | 涉及文件 |
|------|------|---------|---------|
| **标准报告页** | 使用 `var(--color-primary)` 等 Token | 顶栏 + 侧栏目录 + 主内容 | ~33 个 |
| **自定义样式页** | 独立色板(如 `--primary: #1a3a5c`) | 至少顶栏 + 返回链接 | ~7 个 |
| **特殊布局页** | Canvas/Reveal.js/简历 | 至少返回链接 | ~3 个 |
> ⚠️ 遇到自定义样式页时,**不要将其"修复"为 Fluent 2 标准模板**。这些页面刻意使用独立设计语言(如 `银行业Agent建设方案` 的深蓝+橙色金融风格、`深国际综合改革方案` 的暗红+金色政务风格)。
## UI 设计规范
所有页面遵循 `.claude/design-tokens.md` 中的 **Microsoft Fluent 2 / Windows 11** 设计规范(2026-06 从 Ant Design v5 迁移)。关键约束:
所有页面遵循 `.claude/design-tokens.md` 中的 **Microsoft Fluent 2 / Windows 11** 设计规范(2026-06 从 Ant Design v5 迁移)。
> 📖 **`.claude/design-tokens.md` 是权威参考**。它包含完整的色彩阶梯、组件规范、字号表、间距表、材质/动效参数、z-index 层级、响应式断点,以及新页面创建检查清单。下文仅列出最常用的速查值,完整规范务必查阅该文件。
**快速参考**
- **配色方案**:品牌色 `#0078D4`Fluent 2 Communication Blue),功能色(成功 `#107C10`、警告 `#FF8C00`、错误 `#FF4D4F`
- **字体规范**:基准字号 14px,行高 20px,字体族 `Segoe UI Variable Text``Segoe UI``PingFang SC` / `Microsoft YaHei` 回退;等宽字体 `Cascadia Code``Fira Code``SF Mono`
- **圆角体系**`2px / 4px / 6px / 8px` 四级(Fluent 2 更方正)
@@ -121,13 +152,35 @@ wikiData (声明式) → allItems (展开数组, 附加 section/icon) → 视图
创建新 HTML 页面时应直接复用 `:root` CSS 变量块,不要重新定义颜色值。完整规范详见 `.claude/design-tokens.md`
### 新页面检查清单(详见 `.claude/design-tokens.md` §17.5
新建报告页时必须逐项检查:
- [ ] 顶部固定导航栏(64px, sticky top:0
- [ ] `← 返回知识库` 链接,href 按目录深度计算
- [ ] 左侧 260px 侧栏,含按 `<h2>` 标题生成的目录
- [ ] 所有 `<h2>``id` 锚点
- [ ] 使用 CSS 变量(`var(--color-primary)` 等)而非硬编码颜色
- [ ] 移动端(≤768px)隐藏侧栏,全宽布局
- [ ] `font-family` 引用 `var(--fluent-font-family-text)`
- [ ] 内容区 `max-width: 1200px` 居中
## Graphify 知识图谱
本项目已集成 graphify-rs 知识图谱。图谱输出位于 `graphify-out/` 目录按需生成,默认不存在,需手动构建)。
本项目已集成 graphify-rs 知识图谱。图谱输出位于 `graphify-out/` 目录**按需生成**(当前不存在,需手动构建)。
首次构建:
```bash
graphify-rs build --path . --output graphify-out --no-llm
```
日常更新(修改代码后):
```bash
graphify-rs build --path . --output graphify-out --no-llm --update
```
约 2-5sAST-only 模式。
- 架构/代码库问题:如果 `graphify-out/` 存在,先读取 `graphify-out/GRAPH_REPORT.md` 了解核心节点和社区结构
- 如果 `graphify-out/wiki/index.md` 存在,优先导航该索引而非直接读取原始文件
- 修改代码文件后,运行 `graphify-rs build --path . --output graphify-out --no-llm --update` 保持图谱更新(AST-only,约 2-5s
- graphify-rs 使用手册参考 `graphify-rs使用手册/` 目录
## 项目级 Skills
@@ -137,7 +190,36 @@ wikiData (声明式) → allItems (展开数组, 附加 section/icon) → 视图
| 技能 | 说明 | 触发方式 |
|------|------|---------|
| `remote-sync` | rsync 增量同步到远端服务器,自动排除 `node_modules`/`.git` 等 | `/remote-sync` 手动调用 |
| `deep-research` | 生成格式控制的研究报告,含证据追踪、引用治理和多轮综合 | `/deep-research` 手动调用 |
| `deep-research` | 多阶段深度研究报告(P0-P7 pipeline):Lead Agent 协调子代理并行调研 → 引用注册表 → 证据映射提纲 → 反审核 → 验证。支持通用研究与企业研究(六维框架+SWOT+风险矩阵)两种模式 | `/deep-research` 或触发词("调研"、"深度研究"、"行业报告"等) |
| `ui-ux-pro-max` | UI/UX 设计与前端实现辅助 | 按需调用 |
`deep-research` 技能包含参考资料(`.claude/skills/deep-research/references/`)和调研笔记(`research-notes/`),执行深度研究时会用到。
## 项目管理(AI Coding 工作流)
本项目使用 **方案 BGitea + Markdown 项目仪表板** 进行 AI 编码项目管理。
### 核心文件
| 文件 | 作用 |
|------|------|
| `KANBAN.md` | 项目看板:待办/进行中/已完成/问题/定期维护,Claude Code 启动时自动读取 |
| `specs/` | 需求规格文档(喂给 AI 的输入源),每个功能模块一个 `.md` 文件 |
| `sessions/` | AI 编码会话沉淀:每次有价值的会话后记录关键结论、踩坑、审查要点 |
| `prompts/` | 已验证的可复用 Prompt 模式,从 `sessions/` 提炼而来 |
### 工作流
```
KANBAN.md 选取任务 → specs/ 写规格 → Claude Code 生成代码
→ 人工审查 → git commit → sessions/ 记录心得
→ prompts/ 提炼模式 → KANBAN.md 更新状态 → push 部署
```
### 任务状态标签
- `C-*` — 内容建设(新报告页、文章)
- `U-*` — UI/UX 改进(样式、布局、响应式)
- `I-*` — 基础设施(部署、升级、工具)
> ⚠️ `KANBAN.md` 是 AI 理解项目状态的入口。修改代码前,确保看板状态与实际一致。
+114
View File
@@ -0,0 +1,114 @@
# 项目看板 — 一人公司开发团队知识库
> 最后更新: 2026-06-20 · 当前分支: `main` · [仓库首页](https://gitea.home/zdh/wiki)
本文件是 AI Coding 工作面板。Claude Code 打开仓库时会自动读取此文件和 `CLAUDE.md` 来理解项目状态。
---
## 📋 待办 (Backlog)
### 内容建设
| ID | 任务 | 规格 | 预估 | 优先级 |
|----|------|------|------|--------|
| C-01 | 为所有新增报告页添加 wikiData 索引条目 | — | S | 🔴 高 |
| C-02 | `银行业Agent建设方案/` — 完成报告页并入库 | — | M | 🟡 中 |
| C-03 | `AI Agent 驾驭工程/` — 完成报告页并入库 | — | M | 🟡 中 |
| C-04 | `简历AI技术讲解.html` — 完成页面并入库 | — | S | 🟢 低 |
| C-05 | `Dify部署分析报告.html` — 审查后入库 | — | S | 🟡 中 |
### UI/UX 改进
| ID | 任务 | 规格 | 预估 | 优先级 |
|----|------|------|------|--------|
| U-01 | 新增页面移动端适配检查(≤768px) | — | M | 🟡 中 |
| U-02 | 侧栏导航版报告页统一 Fluent 2 变量引用 | — | L | 🟢 低 |
| U-03 | `index.html` 暗色模式下卡片色对比度微调 | — | XS | 🟢 低 |
### 基础设施
| ID | 任务 | 规格 | 预估 | 优先级 |
|----|------|------|------|--------|
| I-01 | Gitea 版本升级(检查最新版功能) | — | S | 🟢 低 |
| I-02 | graphify-rs 重新构建知识图谱 | — | S (2-5s) | 🟡 中 |
| I-03 | 清理根目录散落的单文件(是否需要归入子目录) | — | M | 🟢 低 |
---
## 🔨 进行中 (In Progress)
| ID | 任务 | 会话 | 状态 |
|----|------|------|------|
| CUR-01 | **更新 CLAUDE.md** — 补充 Gitea 部署说明、安全提醒、颜色映射 | — | ⏳ CLAUDE.md 已修改,待提交 |
| CUR-02 | **更新 index.html** — 修改内容待确认 | — | ⏳ 已修改,待提交 |
| CUR-03 | **AI 工具培训系列报告** — Lesson 2-6 页面(`研发型企业AI转型方案/报告/`) | — | 📝 页面已创建,待审查+入库 |
| CUR-04 | **diagrams/** — 新增图表目录 | — | 📝 目录已创建 |
> ⚠️ 当前有 2 个文件已修改未提交(`CLAUDE.md`, `index.html`),多个新目录/文件未跟踪。建议在下一个会话开始前完成提交。
---
## ✅ 已完成 (Done — 本月)
| ID | 任务 | 提交 | 日期 |
|----|------|------|------|
| DONE-06 | 设计系统迁移至 Microsoft Fluent 2 / Windows 11 风格 | `798200c` | 06-14 |
| DONE-05 | 所有页面添加「← 返回知识库」导航链接 | `5167d9e` | 06-13 |
| DONE-04 | 修复返回链接路径 + 添加侧栏目录 + 布局规范 | `9d2851d` | 06-14 |
| DONE-03 | 更新 CLAUDE.md 设计规范至 Fluent 2 + 忽略日志文件 | `1b1b503` | 06-14 |
| DONE-02 | 补充供热行业项目经验至简历 | `667786b` | 06-07 |
| DONE-01 | 添加 AI 使用水平分级页面 | `7256c79` | 06-02 |
---
## 🐛 问题 (Bugs & Issues)
| ID | 描述 | 严重度 | 状态 |
|----|------|--------|------|
| — | 暂无已识别问题 | — | — |
---
## 🔄 定期维护 (Recurring)
| 任务 | 频率 | 上次 | 下次 |
|------|------|------|------|
| `git push` + 验证自动部署 | 每次提交后 | — | — |
| graphify-rs 图谱更新 | 代码结构变更后 | — | 下次结构变更时 |
| 检查 `.gitea/workflows/deploy.yml` 排除列表是否匹配 | 月度 | — | 2026-07-20 |
| Gitea 版本检查 | 季度 | — | 2026-09-20 |
---
## 📁 目录说明
```
项目仓库/
├── KANBAN.md ← 本文件(项目看板)
├── CLAUDE.md ← AI 行为规范(Claude Code 自动读取)
├── specs/ ← 需求规格文档(喂给 AI 的输入)
│ └── README.md
├── sessions/ ← AI 编码会话沉淀
│ └── README.md
├── prompts/ ← 已验证的有效 Prompt 模式
│ └── README.md
├── index.html ← 知识库主页
├── .gitea/ ← CI/CD 配置
│ └── workflows/deploy.yml
└── .claude/ ← Claude Code 配置
├── settings.json
└── skills/
```
## 🧭 工作流
```
1. 从 KANBAN.md 选择任务 → 移动至「进行中」
2. 写 specs/{模块}.md(如需要)
3. Claude Code 打开仓库 → AI 自动读取 CLAUDE.md + specs/ + KANBAN.md
4. AI 生成代码 → 人工审查 → git commit
5. 审核心得写入 sessions/YYYY-MM-DD-{主题}.md
6. 有效 Prompt 模式提炼到 prompts/{场景}.md
7. 更新 KANBAN.md 状态 → git push → 自动部署
```
+34
View File
@@ -0,0 +1,34 @@
# Prompts — 已验证的 Prompt 模式
本目录存放经过验证、可复用的 Prompt 模板。每个文件记录一种被证明有效的 AI 编码交互模式。
## 命名约定
```
{场景描述}.md 例如: 生成CRUD页面.md
```
## 模板结构
```markdown
# {Prompt 模式名称}
## 适用场景
- 什么时候用这个模式
## Prompt 模板
\`\`\`
具体的 Prompt 文本
\`\`\`
## 关键技巧
- 为什么有效
- 需要注意什么
## 来源
- 首次验证: sessions/YYYY-MM-DD-{主题}.md
```
## 与 sessions/ 的关系
`sessions/` 记录原始会话过程,`prompts/` 是从中提炼的可复用模式。不是每个会话都要提炼 Prompt 模式——只有反复验证有效的才沉淀到这里。
@@ -0,0 +1,24 @@
# 项目管理系统搭建
**日期**: 2026-06-20
**触因**: 需要为 AI Coding 工作流配置项目管理方案
## 做了什么
1. 评估了代码托管 + AI 开发项目管理的各种方案
2. 选定方案 BGitea + Markdown 项目仪表板(`KANBAN.md`
3. 创建目录结构:`specs/``sessions/``prompts/`
4. 编写 `KANBAN.md` 项目看板,含当前进度和历史
5. 更新 `CLAUDE.md` 增加项目管理工作流说明
## 决策
- **不引入新工具**Plane / GitLab 等),保持零运维成本
- 看板文件(`KANBAN.md`)放在仓库根目录,Claude Code 自动读取
- 任务 ID 用前缀区分类型:`C-` 内容、`U-` UI、`I-` 基础设施
## 关键结论
- 一人开发团队不需要 Sprint 燃尽图、WIP 限制这些多人协作工具
- AI Coding 的核心资产是:需求规格的质量 + CLAUDE.md 上下文 + 审查能力
- 最好的项目管理工具是 AI 能直接读懂的 Markdown 文件
+18
View File
@@ -0,0 +1,18 @@
# Sessions — AI Coding 会话记录
本目录存放 Claude Code 会话的沉淀笔记。每次有价值的 AI 编码会话后,记录关键结论。
## 命名约定
```
YYYY-MM-DD-{主题}.md 例如: 2026-06-20-库存盘点模块.md
```
## 记录内容
- **做了什么**:任务简述
- **Prompt 模式**:哪些 Prompt 描述方式效果好的(可提炼到 `prompts/`
- **踩坑**:AI 出错的地方、修正方法
- **审查要点**:这个模块人工审查时重点关注什么
- **决策**:技术选型决策及原因
- **关联**:对应的 Issue/PR/commit
+40
View File
@@ -0,0 +1,40 @@
# Specs — 需求规格
本目录存放各功能模块的需求规格文档。每个 Spec 是 Claude Code 生成代码的输入源。
## 命名约定
```
{模块名}.md 例如: 库存盘点模块.md
```
## Spec 模板
创建新 Spec 时参考以下结构:
```markdown
# {功能名称}
## 背景
- 为什么需要这个功能
- 解决什么问题
## 功能描述
- 用户故事或功能点列表
## 技术约束
- 技术栈限制
- 兼容性要求
## 验收标准
- [ ] 标准1
- [ ] 标准2
## 关联
- 依赖: {依赖的 Spec}
- 被依赖: {依赖此 Spec 的模块}
```
## 与 KANBAN.md 的关系
`KANBAN.md` 的 Backlog 条目通过 `specs/{模块名}.md` 路径引用本目录下的规格文档。