跳到文章正文
Claude 实用教程

Claude Code怎么在启动时加载项目状态?SessionStart Hook配置与验证

用只读脚本在新会话加载分支和工作区状态,配置SessionStart matcher并检查上下文…

每次启动Claude Code都复制分支和未提交文件列表,既麻烦又容易过时。SessionStart Hook可以在会话开始或恢复时提供动态上下文。本教程只收集Git状态,不安装依赖、不改文件,也不把启动信息当作批准提交或部署的指令。

Claude Code怎么在启动时加载项目状态?SessionStart Hook配置与验证
Claude Code怎么在启动时加载项目状态?SessionStart Hoo

第一步:把固定规则和动态信息分开

长期编码约定放CLAUDE.md,当前分支、工作区改动等随时间变化的信息再用脚本。Hook每个会话可能运行,内容应短而明确,不把整个仓库或敏感配置打印进去。

在练习仓库备份已有.claude/settings.json,读取现有hooks后合并新增键,不能覆盖其他事件。组织策略可能限制设置来源,选项不生效先查管理规则与实际版本。

第二步:创建只读状态脚本

在项目创建.claude/hooks/session-context.sh,以下脚本仅调用Git读取。先在终端执行确认输出,非Git仓库时返回简短说明。路径假设启动工作目录是项目仓库,实际集成应检查事件输入的cwd。

#!/bin/sh
if ! git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
  printf "%s\n" "当前目录不是Git仓库。"
  exit 0
fi
printf "%s\n" "以下仅为会话启动时的状态快照,执行前请重新检查。"
git branch --show-current
git status --short

第三步:合并SessionStart配置

项目settings.json中的hooks使用事件名SessionStart,matcher可按启动方式选择。示例只匹配startup,避免恢复会话也重复追加;若需要resume或compact,再按官方事件表有意扩展。

用sh执行脚本无需额外赋予可执行位。命令里的路径按你的项目验证,带空格目录或从不同位置启动时尤其要检查。脚本只添加上下文,不是向用户发送消息。

{"hooks":{"SessionStart":[{"matcher":"startup","hooks":[{"type":"command","command":"sh .claude/hooks/session-context.sh"}]}]}}

第四步:验证上下文与事件匹配

新建会话后要求Claude复述收到的启动状态并标注它是快照,核对分支与文件列表。再恢复旧会话,确认只匹配startup的配置没有意外重复运行,不用“启动没有报错”证明内容已进入模型。

官方允许SessionStart的标准输出直接作为上下文;若需要结构化返回,可用hookSpecificOutput、hookEventName和additionalContext。普通调试日志不要混在JSON输出中,也不要把脚本失败伪装成空工作区。

验收提示:仅说明启动Hook提供的分支和改动快照,并指出它可能过时。不要修改文件、提交或运行安装命令。若没有收到Hook信息,明确说没有,不猜测。

第五步:控制启动负担和可恢复性

Hook应快速结束,避免网络访问与长测试拖住第一轮响应。官方说明用户可在部分情况下先输入,但首轮回应仍需等待Hook上下文,不应把慢脚本放到每次启动。

状态快照不能替代行动前重新读取Git,也不扩大工具权限。确认无误后记录脚本用途、matcher和回滚方式;停用时只删除本次新增配置,保留原事件与备份,便于定位后续版本变化。

官方资料

资料核对日期:2026年11月20日。

本文地址:https://www.163264.com/22104