# Claude Code 项目模板

AI 辅助开发知识系统模板，包含开发日志、踩坑追踪、延期方案管理、问题蒸馏、画像记忆、Skill 调度等完整基础设施。

## 目录结构

```
.claude/
├── CLAUDE.md                        # 主入口文件，@import 引入所有规则
├── settings.json                    # Hooks 配置 + 权限
├── settings.local.example.json      # 本地配置模板
├── rules/
│   └── common/                      # 通用规则（8 条）
│       ├── baserule.md              # 语言约定、目录归属
│       ├── claude-init-recall.md    # 首次会话自动触发初始化
│       ├── changelog-recall.md      # 开发日志注入 + 任务完成 Checklist
│       ├── deferred-recall.md       # 延期方案主动提醒
│       ├── distillery-recall.md     # Golden Rules 注入 + 蒸馏提醒
│       ├── epee-orchestrator.md     # Skill 触发雷达 + Registry 同步
│       ├── pitfall-recall.md        # 踩坑经验自动检索
│       └── profile-recall.md        # 用户/项目画像注入
├── skills/                          # 能力模块（7 个）
│   ├── claude-init/                 # 项目初始化（7 阶段流程）
│   ├── dev-changelog/               # 三层开发日志
│   ├── deferred-decisions/          # 延期方案追踪
│   ├── pitfall-journal/             # 踩坑记录与检索
│   ├── problem-distillery/          # 顽固问题蒸馏 → Golden Rules
│   ├── profile-memory/              # 用户/项目画像管理
│   └── epee-orchestrator/           # Skill 调度 + Registry 维护
│       └── registry.md              # Skill 注册表
├── hooks/                           # 事件钩子
│   ├── run-hook.ps1                 # Windows 分发器
│   ├── session-init.ps1/.sh         # SessionStart: 清除 ack 标记
│   ├── check-changelog.ps1/.sh      # Stop: 检查 changelog 同步
│   └── README.md                    # Hooks 说明
├── changelog/                       # 三层开发日志数据
│   ├── changelog-full.md            # L1 完整版
│   ├── changelog-recent.md          # L2 近期摘要
│   └── changelog-headlines.md       # L3 一句话概要
├── deferred/registry.md             # 延期方案注册表
├── pitfalls/pitfalls.md             # 踩坑记录
├── distillery/                      # 问题蒸馏数据
│   ├── problems.md                  # 顽固问题追踪
│   ├── insights.md                  # 蒸馏后的方法论
│   └── golden-rules.md              # 经验证的 Golden Rules
├── profile/                         # 项目画像
│   ├── project-profile.md           # 精简版
│   └── project-profile-log.md       # 详细日志
└── plans/                           # 规划文档（空目录）
```

## 快速开始

### 首次使用

克隆模板仓库后，首次进入项目目录时 `claude-init` Skill 会自动触发，完成初始化。

### 每日流程

1. 正常开发和修改代码
2. 任务完成后，changelog-recall 的 Checklist 自动提醒记录日志
3. Stop Hook 检查 changelog 同步状态，发现未记录时提醒

## 核心系统

### 三层开发日志

| 层级 | 自动注入 | 用途 |
|------|---------|------|
| L3 Headlines | 每次会话 | 一句话概要，快速定位感 |
| L2 Recent | 检测到关联时 | 摘要记录，理解改动上下文 |
| L1 Full | 手动唤醒 | 完整记录，溯源决策背景 |

### 问题蒸馏生命周期

```
踩坑 (pitfall) → 顽固问题追踪 (distillery/problems)
     → 蒸馏方法论 (distillery/insights)
     → 验证升级 (golden-rules) → 自动注入新会话
```

### 任务完成 Checklist

每次回复前强制执行：
1. 画像信号扫描（前置项 A）
2. 代码改动 → 写入三层日志
3. Skill 变更 → 同步 Registry
4. Skill 异常 → 触发自迭代
5. 静默 Hook ack（收尾项 Z）

## 配置说明

### 跨平台

- Windows：默认 PowerShell
- macOS/Linux：修改 `settings.local.json` 的 `shell` 为 `bash`，参考 `hooks/README.md`

### 权限

在 `settings.json` 或 `settings.local.json` 的 `permissions.allow` 中添加需要的权限。

## 常见问题

**Q: 如何禁用某个 Rule？**
编辑 `CLAUDE.md`，注释掉对应的 `@import` 行。

**Q: 如何添加新 Skill？**
在 `.claude/skills/` 下创建新目录和 `SKILL.md`，然后更新 `epee-orchestrator/registry.md`。

**Q: Stop Hook 总是提醒更新 changelog？**
确认是否确实修改了源文件但未记录。如果已通过 Checklist 完成记录，ack 文件会阻止重复提醒。