db-skill: Project Development Knowledge Tracker

Violating the letter of the rules is violating the spirit of the rules.

Overview

db-skill 自动追踪每个开发任务到 Notion 数据库。开发 → 记录 → 查询 → 增强，核心链路闭环。

Quick Start

1. 安装 db-skill

# 一键安装 skill 到全局 (~/.claude/skills/)
npx db-skill

# 或显式指定安装
npx db-skill --install

2. 安装 Notion CLI 依赖

npm install -g @notionhq/notion-cli
notion auth login

3. 初始化项目

/db-skill init <项目描述>
# 例如: /db-skill init B端电商管理系统

3. 自动使用

Save (记录) - 完成后自动记录：

/db-skill save

Query (查询) - 解决问题前自动查询：

/db-skill query <问题描述>

Ref (引用) - 跨项目引用：

/db-skill ref add <database-id>

核心规则

Iron Laws

1. EVERY COMPLETED TASK MUST BE RECORDED - 无例外
2. EVERY NEW TASK MUST QUERY FIRST - 无例外

触发条件

• 完成任何开发任务时
• 遇到错误或 bug 时
• 开始可能已有解决方案的功能时
• 用户说 /db-skill 时

数据结构

本地文件

.db-skill/
├── config.json      # 项目配置（databaseId、refs）
├── index.json       # 条目索引（L1 查询）
├── entries/*.md     # 条目摘要（L2 详情）
├── pending/         # 离线暂存
└── .gitignore       # 排除敏感文件

Notion Schema

| 属性 | 类型 | 说明 | |------|------|------| | Title | title | 简洁标题（如 "用户列表分页不刷新"） | | Type | select | Feature / Bug Fix / Decision / Refactor | | Tags | multi_select | 技术标签（如 Vue, React, API, DB） | | Status | status | Not started / In progress / Resolved | | Severity | select | Low / Medium / High / Critical | | Summary | rich_text | 一句话总结（≤50 chars） | | Root Cause | rich_text | Bug 根因（仅 Bug 填写） | | Fix Points | rich_text | 修复要点（仅 Bug 填写） | | Files Changed | rich_text | 修改的具体文件 | | Error Pattern | rich_text | 错误特征（精确匹配用） | | Related | rich_text | 关联的其他条目 ID | | Hit Count | number | 查询命中次数 |

数据库名称: <项目名称>（如 "B端电商管理系统"）

CLI 命令

# 初始化
/db-skill init <project description>

# 查询（解决问题前必须）
/db-skill query <keywords>

# 查看所有条目
/db-skill list

# 跨项目引用
/db-skill ref add <database-id>
/db-skill ref list
/db-skill ref remove <database-id>

离线支持

Notion CLI 失败时自动：

1. 保存到 .db-skill/pending/
2. 更新 index.json (synced: false)
3. 网络恢复后自动同步

项目结构

db-skill/
├── SKIIL.md              # Skill 源文件
├── README.md            # 本文档
├── scripts/             # CI/CD 脚本
│   ├── lint-skill.sh
│   ├── validate-structure.sh
│   └── check-cso.sh
├── tests/
│   ├── baseline/        # RED 阶段测试
│   ├── smoke/           # GREEN 阶段冒烟测试
│   └── pressure/        # REFACTOR 阶段压力测试
└── versions/            # 版本存档

CI/CD

make ci              # 运行全部检查 (lint + structure + cso)
make lint            # 软指令检查
make structure       # 结构验证
make cso             # CSO 合规检查
make test            # 压力测试
make deploy VERSION=v1.0  # 部署到 ~/.claude/skills/

许可证

MIT