# CLAUDE.md Guardian Agent

后台 agent，监控项目变化并自动维护 CLAUDE.md 文件。

## 触发条件

- Session 启动时（通过 SessionStart hook）
- 重大里程碑后（feature 完成、重构、新依赖、架构变化）

## 监控范围

| 变化类型 | 检测方式 | 更新内容 |
|----------|----------|----------|
| 目录结构变化 | 对比 `.claude/guardian/structure.json` | 项目结构图 |
| 依赖变化 | package.json, requirements.txt 等 | Tech Stack 部分 |
| 新增 skill | `.claude/skills/` 目录变化 | Skills 清单 |
| 新增命令 | `.claude/commands/` 目录变化 | 命令列表 |
| 架构变化 | 手动标记 | 架构说明 |

## 工作流程

```
SessionStart Hook
    ↓
检查 .claude/guardian/snapshot.json 是否存在
    ↓
    ├─ 不存在 → 首次运行，创建快照，不更新
    └─ 存在 → 对比当前状态与快照
              ↓
              ├─ 无变化 → 静默退出
              └─ 有变化 → 生成更新建议，询问用户
```

## 快照格式

```json
{
  "last_check": "2026-03-02T10:00:00+08:00",
  "structure_hash": "abc123",
  "skills": ["write-article", "my-world"],
  "commands": ["/today", "/close", "/emerge", "/challenge", "/connect", "/my-world"],
  "dependencies": {
    "bash": ["obsidian-cli"],
    "obsidian_plugins": ["dataview", "templater-obsidian", "note-to-mp", "obsidian-kanban"]
  }
}
```

## 更新原则

1. **保守更新**：只添加缺失信息，不删除现有内容
2. **用户确认**：重大变化前询问用户
3. **版本追踪**：每次更新记录版本号和日期
4. **保持简洁**：CLAUDE.md 控制在 400 行以内

## 配置文件

项目级 settings.json 中配置 hook：

```json
{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bash .claude/hooks/guardian-check.sh"
          }
        ]
      }
    ]
  }
}
```

## 版本

- **版本**: 1.0.0
- **创建日期**: 2026-03-02
- **适用项目**: content-forge