# Devlog · 开发过程自动记录

这个目录由 `.claude/hooks/` 下的 4 个脚本自动维护,记录 Claude Code 在本项目里的所有开发活动。

## 文件结构

```
devlog/
├── README.md            # 本文件
├── 2026-05-29.md        # 按日期的活动日志(自动追加)
├── 2026-05-30.md
├── ...
└── transcripts/         # 完整对话 transcript(.gitignore,本地保留)
    └── <session-id>.jsonl
```

## 日志格式

每天一个 `YYYY-MM-DD.md` 文件,内部按 session 分段:

```markdown
# Devlog · 2026-05-29

---

## Session `abc12345` · started 17:49:24

- `17:49:25`  **Edit**  `path/to/file.md`
- `17:49:30`  **Bash**  `git status --short`
- `17:50:12`  **Read**  `path/to/other.html`

### `17:51:00` git commit `01dd706`

> Add 24-week development roadmap

_2 files changed, 962 insertions(+)_

变更文件:
- `docs/roadmap.md`
- `roadmap.html`

_session `abc12345` · last activity 17:55:18 · transcript [`abc12345-...jsonl`](transcripts/abc12345-...jsonl) (692K, 179 lines)_
```

## Hook 映射

| Hook 事件 | 脚本 | 作用 |
|---|---|---|
| `SessionStart` | `session-start.sh` | 在今日 md 末尾写一段 session 起始标题 |
| `PostToolUse` (`.*`) | `log-tool.sh` | 每次工具调用追加一行(时间 / 工具名 / 关键参数) |
| `PostToolUse` (`Bash`, `if Bash(git commit*)`) | `log-commit.sh` | 每次 `git commit` 后追加 commit hash / message / 文件清单 |
| `SessionEnd` | `session-end.sh` | 写 session 结束标记 + 把当前 transcript jsonl 复制到 `transcripts/` |

## 何时生效

Hooks 在 Claude Code **启动时**加载 `.claude/settings.json`。所以:

- **当前会话(创建 hooks 的这一个)不会触发**,因为 settings.json 在会话开始之后才出现。
- 下一次在 `InvesResearch-site/` 目录下打开 Claude Code,hooks 自动启用。
- 也可以在当前会话敲 `/hooks` 打开 hooks UI,Claude Code 会重新加载配置。

## 重要:启动目录要求

这个 `.claude/settings.json` 是 **project-scoped**,只在 Claude Code 的 cwd 是 `InvesResearch-site/`(或其子目录)时生效。如果你从父目录 `/Users/john/InvesResearch/` 启动 Claude Code,这些 hooks 不会加载。

推荐启动方式:
```bash
cd /Users/john/InvesResearch/InvesResearch-site
claude
```

## Transcripts 隐私

`transcripts/*.jsonl` 是完整对话原文,被 `.gitignore` 排除,只保留本地副本。原因:

- 体积大(单次会话往往 500 KB ~ 几 MB)
- 包含完整用户输入,可能涉及 API key、内部决策等敏感信息
- 公开 repo 不应自动同步

若你确认某次 transcript 可以公开归档,手动 `git add -f devlog/transcripts/<id>.jsonl` 即可。

Claude Code 本身已经在 `~/.claude/projects/<sanitized-cwd>/` 下自动保留所有 transcript,这里的副本只是"提交边界内"的方便引用。

## 关闭或调整

- 临时关闭所有 hooks:`.claude/settings.json` 顶层加 `"disableAllHooks": true`
- 单独关掉某个 hook:在 `.claude/settings.json` 里删除对应条目
- 修改记录格式:直接编辑 `.claude/hooks/*.sh`

## 故障排查

如果某次操作没被记录:
1. 确认是从 `InvesResearch-site/` 启动的 Claude Code(`pwd` 检查)
2. 在会话内敲 `/hooks` 查看 hooks 是否被加载
3. 手动跑一次脚本 pipe-test:
   ```bash
   echo '{"tool_name":"Edit","tool_input":{"file_path":"/tmp/test"}}' | .claude/hooks/log-tool.sh
   tail -1 devlog/$(date +%Y-%m-%d).md
   ```
4. 检查脚本可执行权限:`ls -l .claude/hooks/*.sh`(都应是 `-rwxr-xr-x`)