project-context

在不同 Claude 会话之间维护项目上下文和进度跟踪。通过在会话开始时加载上下文、结束时保存进度，实现无缝的会话衔接。

<quick_start> 会话开始： 加载 <project-root>/.claude/PROJECT_CONTEXT.md，并对照 git status 进行验证

会话结束： 用已完成的 TODO 更新上下文文件，并清空上一会话的 Done 列表

上下文文件位置： <project-root>/.claude/PROJECT_CONTEXT.md

触发语句： “加载上下文”、“保存上下文”、“今天到此为止”、“切换到 [project]” </quick_start>

<success_criteria> 满足以下条件时，上下文管理即为成功：

• 从 pwd（Claude Code）或用户输入（Claude Desktop）检测到项目
• 上下文文件与当前项目匹配（根据文件夹名称验证标题）
• 根据上下文验证 Git 状态（分支、近期提交）
• 每个新会话都清空 Done 列表（防止内容不断累积）
• 会话结束前保存上下文 </success_criteria>

<core_content>

必须：检测项目（首先执行）

在执行任何其他操作之前，先识别用户所在的项目：

Claude Code（终端）

pwd  # Get current working directory

1. 运行 pwd 获取当前目录
2. 从路径中提取项目名称（最后一个文件夹名称）
3. 加载 <pwd>/.claude/PROJECT_CONTEXT.md
4. 验证：# <project-name> 标题是否与文件夹名称匹配？
   • 是 → 显示上下文并继续
   • 否 → 警告：“上下文不匹配！文件中记录的是 [X]，但你所在的是 [Y]。正在重新生成……”
   • 文件不存在 → 自动生成（见下文）

Claude Desktop（无终端）

如果 pwd 不可用（Claude Desktop 环境）：

1. 检查用户是否已在消息中指定项目
2. 如果没有，询问：“你今天要处理哪个项目？”
3. 如果可用，使用 reference/projects-list.md 中的项目列表
4. 加载：/Users/tmk/Desktop/tk_projects/{project-name}/.claude/PROJECT_CONTEXT.md

切换项目：用户说“切换到 [project-name]”或“正在处理 [project]”

---

会话开始时

检测到项目后：

1. 加载上下文文件

<project-root>/.claude/PROJECT_CONTEXT.md

2. 对照 Git 状态进行验证

git status            # Current branch, modified files
git log --oneline -5  # Recent commits

标记差异：

• 提交中已完成的 TODO？→ 移至“Done”
• 分支已更改？→ 更新上下文标题
• 信息已过时？→ 删除

3. 向用户展示

显示简要摘要：

📍 Project: [name]
🌿 Branch: [branch]
📅 Last updated: [date]

Focus items: [count]

---

会话结束时

触发语句：“完成”、“结束会话”、“保存上下文”、“今天到此为止”

1. 检查对话中已完成的工作
2. 更新 PROJECT_CONTEXT.md：
   • 将已完成的 TODO 移至“Done (This Session)”
   • 根据已创建的提交更新状态
   • 保留未更改的 Focus 项
   • 清空上一会话的 Done 列表（防止内容不断累积）
   • 更新时间戳
3. 向用户显示更新后的上下文

---

自动生成上下文

如果不存在 PROJECT_CONTEXT.md，则根据以下内容创建：

1. .claude/CLAUDE.md 或 CLAUDE.md（项目文档）
2. git log --oneline -5（近期活动）
3. git status（当前状态）
4. package.json / pyproject.toml / requirements.txt（技术栈）

写入：<project-root>/.claude/PROJECT_CONTEXT.md

---

上下文文件格式

完整模板请参见 reference/template.md。

# <project-name>

**Branch**: <branch> | **Updated**: <YYYY-MM-DD>

## Status
<2-3 sentences: current state>

## Today's Focus
1. [ ] <task>
2. [ ] <task>

## Done (This Session)
- <populated on session end, cleared on next session start>

## Blockers
<none or list>

## Tech Stack
<single line: Python 3.11 | FastAPI | PostgreSQL>

---

关键规则

1. 始终先检测项目——绝不根据上一会话进行假设
2. 一个项目对应一个上下文文件——避免项目间内容混杂
3. 验证上下文与 pwd 匹配——不匹配时发出警告
4. 每个会话都清空 Done 列表——防止内容无限累积
5. 绝不将数据存储在此 SKILL.md 中——始终使用项目自己的文件

---

参考文件

• reference/template.md - 完整的上下文文件模板和示例
• reference/projects-list.md - Tim 的项目列表，供 Claude Desktop 使用

写入结果旁文件

最后一步，写入 ~/.claude/skill-analytics/last-outcome-project-context.json：

{"ts":"[UTC ISO8601]","skill":"project-context","version":"1.0.0","variant":"default",
 "status":"[success|partial|error]","runtime_ms":[estimated ms from start],
 "metrics":{"projects_detected":[n],"context_files_updated":[n]},
 "error":null,"session_id":"[YYYY-MM-DD]"}

如果某些阶段失败但仍产生了结果，请使用状态 "partial"。只有在未生成任何输出时才使用 "error"。 </core_content>