session-management by alinaqi/claude-bootstrap
npx skills add https://github.com/alinaqi/claude-bootstrap --skill session-management加载方式:base.md
用于在长时间的开发会话中保持上下文,并支持在中断后无缝恢复。
在自然断点处创建检查点,实现即时恢复。
长时间的开发会话存在上下文丢失的风险。主动记录状态、决策和进度,以便任何会话都能从上次中断的地方准确恢复——无论是休息后返回还是达到上下文限制。
触发条件:完成任何小任务或待办事项后 操作:更新"当前任务"、"进度"和"后续步骤"部分 耗时:约 30 秒
触发条件:
操作:
触发条件:
操作:
archive/YYYY-MM-DD[-topic].md广告位招租
在这里展示您的产品或服务
触达数万 AI 开发者,精准高效
┌─────────────────────────────────────────────────────┐
│ 完成工作后,自问: │
├─────────────────────────────────────────────────────┤
│ 是否做出了决策? → 记录到 decisions.md │
│ 任务耗时 >10 次工具调用? → 完整检查点 │
│ 主要功能完成? → 归档 │
│ 会话结束? → 归档 + 交接 │
│ 其他情况 → 快速更新 │
└─────────────────────────────────────────────────────┘
创建 _project_specs/session/ 目录:
_project_specs/
└── session/
├── current-state.md # 实时会话状态(频繁更新)
├── decisions.md # 关键决策日志(仅追加)
├── code-landmarks.md # 重要代码位置
└── archive/ # 过往会话摘要
└── 2025-01-15.md
_project_specs/session/current-state.md - 每 15-20 分钟或在取得重大进展后更新。
# 当前会话状态
*最后更新:2025-01-15 14:32*
## 当前任务
[一句话:我们当前正在做什么]
示例:使用 JWT 令牌实现用户认证流程
## 当前状态
- **阶段**:[探索 | 规划 | 实现 | 测试 | 调试 | 重构]
- **进度**:[X of Y 步骤完成,或百分比]
- **阻塞问题**:[无,或描述阻塞项]
## 上下文摘要
[2-3 句话总结当前工作状态]
示例:创建了认证中间件和登录端点。JWT 签名有效。
当前正在实现令牌刷新逻辑。需要为安全性添加刷新令牌轮换。
## 正在修改的文件
| 文件 | 状态 | 备注 |
|------|--------|-------|
| src/auth/middleware.ts | 完成 | JWT 验证 |
| src/auth/refresh.ts | 进行中 | 令牌轮换 |
| src/auth/types.ts | 完成 | 令牌接口 |
## 后续步骤
1. [ ] 在 refresh.ts 中完成刷新令牌轮换
2. [ ] 为登出添加令牌黑名单
3. [ ] 为认证流程编写集成测试
## 需要保留的关键上下文
- 根据安全要求使用 RS256 算法(而非 HS256)
- 刷新令牌存储在 HttpOnly cookie 中
- 访问令牌:15 分钟,刷新令牌:7 天
## 恢复说明
要继续此工作:
1. 阅读 src/auth/refresh.ts - 当前在第 45 行
2. rotateRefreshToken() 函数需要错误处理
3. 查看 decisions.md 了解我们为何选择 RS256 而非 HS256
_project_specs/session/decisions.md - 架构和实现决策的仅追加日志。
# 决策日志
记录关键决策以供将来参考。切勿删除条目。
---
## [2025-01-15] JWT 算法选择
**决策**:使用 RS256 而非 HS256 进行 JWT 签名
**上下文**:实现认证系统
**考虑过的选项**:
1. HS256(对称)- 更简单,单一密钥
2. RS256(非对称)- 公钥/私钥对
**选择**:RS256
**理由**:
- 允许在不暴露签名密钥的情况下验证令牌
- 更适合微服务(服务仅需公钥)
- 生产系统的行业标准
**权衡**:
- 密钥管理稍复杂
- 令牌尺寸更大
**参考**:
- src/auth/keys/ - 密钥存储
- docs/security.md - 安全架构
---
## [2025-01-14] 数据库模式方法
**决策**:使用 Drizzle ORM 与 PostgreSQL
**上下文**:设置数据层
**考虑过的选项**:
1. Prisma - 流行,开发者体验好
2. Drizzle - 类型安全,类 SQL
3. 原始 SQL - 最大控制权
**选择**:Drizzle
**理由**:
- 比 Prisma 的 TypeScript 推断更好
- SQL 生成更透明
- 更轻量,冷启动更快
**参考**:
- src/db/schema.ts - 模式定义
- src/db/migrations/ - 迁移文件
_project_specs/session/code-landmarks.md - 重要代码位置,便于快速参考。
# 代码地标
代码库重要部分的快速参考。
## 入口点
| 位置 | 用途 |
|----------|---------|
| src/index.ts | 主应用程序入口 |
| src/api/routes.ts | API 路由定义 |
| src/workers/index.ts | 后台作业入口 |
## 核心业务逻辑
| 位置 | 用途 |
|----------|---------|
| src/core/auth/ | 认证系统 |
| src/core/billing/ | 支付处理 |
| src/core/workflows/ | 主工作流引擎 |
## 配置
| 位置 | 用途 |
|----------|---------|
| src/config/index.ts | 环境配置 |
| src/config/features.ts | 功能开关 |
| drizzle.config.ts | 数据库配置 |
## 关键模式
| 模式 | 示例位置 | 备注 |
|---------|------------------|-------|
| 服务层 | src/services/user.ts | 业务逻辑封装 |
| 仓库 | src/repos/user.ts | 数据访问抽象 |
| 中间件 | src/middleware/auth.ts | 请求处理 |
## 测试
| 位置 | 用途 |
|----------|---------|
| tests/unit/ | 单元测试 |
| tests/integration/ | API 测试 |
| tests/e2e/ | 端到端测试 |
| tests/fixtures/ | 测试数据 |
## 陷阱与非显而易见行为
| 位置 | 问题 | 备注 |
|----------|-------|-------|
| src/utils/date.ts | 时区处理 | 内部始终使用 UTC |
| src/api/middleware.ts:45 | 认证绕过 | 健康检查跳过认证 |
| src/db/pool.ts | 连接限制 | 开发环境最多 10 个连接 |
将此部分添加到 CLAUDE.md:
## 会话管理
**重要**:遵循 session-management.md 技能。在自然断点处更新会话状态。
### 每次任务完成后
自问:
1. 是否做出了决策? → 记录到 `decisions.md`
2. 是否耗时 >10 次工具调用? → 完整检查点到 `current-state.md`
3. 主要功能是否完成? → 创建归档条目
4. 其他情况 → 快速更新 `current-state.md`
### 检查点触发条件
**快速更新**(current-state.md):
- 任何待办事项完成后
- 小变更后
**完整检查点**(current-state.md + decisions.md):
- 重大变更后
- 约 20 次工具调用后
- 任何决策后
- 切换焦点区域时
**归档**(archive/ + 完整检查点):
- 会话结束时
- 主要功能完成时
- 上下文感觉沉重时
### 会话开始协议
开始工作时:
1. 阅读 `_project_specs/session/current-state.md`
2. 检查 `_project_specs/todos/active.md`
3. 如有需要,查看最近的 `decisions.md` 条目
4. 从"后续步骤"继续
### 会话结束协议
在结束前或接近上下文限制时:
1. 创建归档:`_project_specs/session/archive/YYYY-MM-DD.md`
2. 使用交接格式更新 current-state.md
3. 确保后续步骤具体且可操作
| 触发条件 | 操作 |
|---|---|
| 约 50+ 次工具调用 | 总结进度,归档详细笔记 |
| 主要功能完成 | 归档功能详情,更新地标 |
| 上下文切换 | 总结先前上下文,归档,重新开始 |
| 会话结束 | 完整会话交接并归档 |
在活跃上下文中保留:
归档/总结:
压缩时,使用此格式:
## 压缩上下文 - [主题]
**摘要**:[1-2 句话]
**关键发现**:
- [重要发现的要点]
**做出的决策**:
- [引用 decisions.md 条目]
**相关代码**:
- [文件:行号 引用]
**归档详情**:[如果创建了归档文件,则提供链接]
在重要工作后或会话结束时,创建归档:
_project_specs/session/archive/YYYY-MM-DD[-topic].md
# 会话归档:[日期] - [主题]
## 摘要
[段落总结完成的工作]
## 已完成的任务
- [TODO-XXX] 描述 - 完成
- [TODO-YYY] 描述 - 完成
## 关键决策
- [引用本次会话中做出的 decisions.md 条目]
## 代码变更
| 文件 | 变更类型 | 描述 |
|------|-------------|-------------|
| src/auth/login.ts | 创建 | 登录端点 |
| src/auth/types.ts | 修改 | 添加 RefreshToken 类型 |
## 添加的测试
- tests/auth/login.test.ts - 登录流程测试
- tests/auth/refresh.test.ts - 令牌刷新测试
## 结转的未完成事项
- [任何未完成的事项,现已移至 active.md]
## 会话统计
- 时长:约 3 小时
- 工具调用:约 120 次
- 修改的文件:8 个
- 添加的测试:12 个
在活动待办事项中,引用会话上下文:
## [TODO-042] 实现令牌刷新
**状态:** 进行中
**会话上下文:** 参见 current-state.md
### 进度备注
- 2025-01-15:开始实现,基础结构完成
- 2025-01-15:添加了轮换逻辑,需要错误处理
完成待办事项时:
添加到项目脚本或别名:
# 显示当前会话状态
alias session-status="cat _project_specs/session/current-state.md"
# 快速编辑会话状态
alias session-edit="$EDITOR _project_specs/session/current-state.md"
# 查看近期决策
alias decisions="tail -100 _project_specs/session/decisions.md"
# 创建会话归档
session-archive() {
cp _project_specs/session/current-state.md \
"_project_specs/session/archive/$(date +%Y-%m-%d).md"
echo "已归档至 _project_specs/session/archive/$(date +%Y-%m-%d).md"
}
CLAUDE.md 必须在技能部分引用 session-management.md。Claude 首先读取 CLAUDE.md,这指示其遵循会话规则。
在会话文件头部包含执行提醒:
current-state.md 头部:
<!--
检查点规则(来自 session-management.md):
- 快速更新:任何待办事项完成后
- 完整检查点:约 20 次工具调用或决策后
- 归档:会话结束或主要功能完成时
-->
完成任何任务后,Claude 应自问:
□ 我是否做出了决策? → 记录它
□ 是否耗时 >10 次工具调用? → 完整检查点
□ 功能是否完成? → 归档
□ 我是否要结束/切换上下文? → 归档 + 交接
开始会话时,Claude 必须:
current-state.md 是否存在并读取它每约 20 次工具调用,Claude 应检查:
用户可以通过询问来强制执行:
任务完成?
│
├── 是否做出了决策? ──────────────────→ 记录到 decisions.md
│
├── >10 次工具调用 或 重大? ──→ 完整检查点
│
├── 主要功能完成? ─────────────→ 归档
│
└── 其他情况 ───────────────────────→ 快速更新
| 文件 | 更新频率 | 用途 |
|---|---|---|
| current-state.md | 每个任务 | 实时状态,后续步骤 |
| decisions.md | 决策时 | 架构选择 |
| code-landmarks.md | 模式变更时 | 代码导航 |
| archive/*.md | 会话/功能结束时 | 历史记录 |
每周安装次数
77
仓库
GitHub 星标数
531
首次出现
2026年1月20日
安全审计
安装于
claude-code61
gemini-cli59
opencode59
codex53
cursor52
antigravity50
Load with: base.md
For maintaining context across long development sessions and enabling seamless resume after breaks.
Checkpoint at natural breakpoints, resume instantly.
Long development sessions risk context loss. Proactively document state, decisions, and progress so any session can resume exactly where it left off - whether returning after a break or hitting context limits.
Trigger : After completing any small task or todo item Action : Update "Active Task", "Progress", and "Next Steps" sections Time : ~30 seconds
Trigger :
Action :
Trigger :
Action :
archive/YYYY-MM-DD[-topic].md┌─────────────────────────────────────────────────────┐
│ After completing work, ask: │
├─────────────────────────────────────────────────────┤
│ Was a decision made? → Log to decisions.md │
│ Task took >10 tool calls? → Full Checkpoint │
│ Major feature complete? → Archive │
│ Ending session? → Archive + Handoff │
│ Otherwise → Quick Update │
└─────────────────────────────────────────────────────┘
Create _project_specs/session/ directory:
_project_specs/
└── session/
├── current-state.md # Live session state (update frequently)
├── decisions.md # Key decisions log (append-only)
├── code-landmarks.md # Important code locations
└── archive/ # Past session summaries
└── 2025-01-15.md
_project_specs/session/current-state.md - Update every 15-20 minutes or after significant progress.
# Current Session State
*Last updated: 2025-01-15 14:32*
## Active Task
[One sentence: what are we working on right now]
Example: Implementing user authentication flow with JWT tokens
## Current Status
- **Phase**: [exploring | planning | implementing | testing | debugging | refactoring]
- **Progress**: [X of Y steps complete, or percentage]
- **Blocking Issues**: [None, or describe blockers]
## Context Summary
[2-3 sentences summarizing the current state of work]
Example: Created auth middleware and login endpoint. JWT signing works.
Currently implementing token refresh logic. Need to add refresh token
rotation for security.
## Files Being Modified
| File | Status | Notes |
|------|--------|-------|
| src/auth/middleware.ts | Done | JWT verification |
| src/auth/refresh.ts | In Progress | Token rotation |
| src/auth/types.ts | Done | Token interfaces |
## Next Steps
1. [ ] Complete refresh token rotation in refresh.ts
2. [ ] Add token blacklist for logout
3. [ ] Write integration tests for auth flow
## Key Context to Preserve
- Using RS256 algorithm (not HS256) per security requirements
- Refresh tokens stored in HttpOnly cookies
- Access tokens: 15 min, Refresh tokens: 7 days
## Resume Instructions
To continue this work:
1. Read src/auth/refresh.ts - currently at line 45
2. The rotateRefreshToken() function needs error handling
3. Check decisions.md for why we chose RS256 over HS256
_project_specs/session/decisions.md - Append-only log of architectural and implementation decisions.
# Decision Log
Track key decisions for future reference. Never delete entries.
---
## [2025-01-15] JWT Algorithm Choice
**Decision**: Use RS256 instead of HS256 for JWT signing
**Context**: Implementing authentication system
**Options Considered**:
1. HS256 (symmetric) - Simpler, single secret
2. RS256 (asymmetric) - Public/private key pair
**Choice**: RS256
**Reasoning**:
- Allows token verification without exposing signing key
- Better for microservices (services only need public key)
- Industry standard for production systems
**Trade-offs**:
- Slightly more complex key management
- Larger token size
**References**:
- src/auth/keys/ - Key storage
- docs/security.md - Security architecture
---
## [2025-01-14] Database Schema Approach
**Decision**: Use Drizzle ORM with PostgreSQL
**Context**: Setting up data layer
**Options Considered**:
1. Prisma - Popular, good DX
2. Drizzle - Type-safe, SQL-like
3. Raw SQL - Maximum control
**Choice**: Drizzle
**Reasoning**:
- Better TypeScript inference than Prisma
- More transparent SQL generation
- Lighter weight, faster cold starts
**References**:
- src/db/schema.ts - Schema definitions
- src/db/migrations/ - Migration files
_project_specs/session/code-landmarks.md - Important code locations for quick reference.
# Code Landmarks
Quick reference to important parts of the codebase.
## Entry Points
| Location | Purpose |
|----------|---------|
| src/index.ts | Main application entry |
| src/api/routes.ts | API route definitions |
| src/workers/index.ts | Background job entry |
## Core Business Logic
| Location | Purpose |
|----------|---------|
| src/core/auth/ | Authentication system |
| src/core/billing/ | Payment processing |
| src/core/workflows/ | Main workflow engine |
## Configuration
| Location | Purpose |
|----------|---------|
| src/config/index.ts | Environment config |
| src/config/features.ts | Feature flags |
| drizzle.config.ts | Database config |
## Key Patterns
| Pattern | Example Location | Notes |
|---------|------------------|-------|
| Service Layer | src/services/user.ts | Business logic encapsulation |
| Repository | src/repos/user.ts | Data access abstraction |
| Middleware | src/middleware/auth.ts | Request processing |
## Testing
| Location | Purpose |
|----------|---------|
| tests/unit/ | Unit tests |
| tests/integration/ | API tests |
| tests/e2e/ | End-to-end tests |
| tests/fixtures/ | Test data |
## Gotchas & Non-Obvious Behavior
| Location | Issue | Notes |
|----------|-------|-------|
| src/utils/date.ts | Timezone handling | Always use UTC internally |
| src/api/middleware.ts:45 | Auth bypass | Skip auth for health checks |
| src/db/pool.ts | Connection limit | Max 10 connections in dev |
Add this section to CLAUDE.md:
## Session Management
**IMPORTANT**: Follow session-management.md skill. Update session state at natural breakpoints.
### After Every Task Completion
Ask yourself:
1. Was a decision made? → Log to `decisions.md`
2. Did this take >10 tool calls? → Full checkpoint to `current-state.md`
3. Is a major feature complete? → Create archive entry
4. Otherwise → Quick update to `current-state.md`
### Checkpoint Triggers
**Quick Update** (current-state.md):
- After any todo completion
- After small changes
**Full Checkpoint** (current-state.md + decisions.md):
- After significant changes
- After ~20 tool calls
- After any decision
- When switching focus areas
**Archive** (archive/ + full checkpoint):
- End of session
- Major feature complete
- Context feels heavy
### Session Start Protocol
When beginning work:
1. Read `_project_specs/session/current-state.md`
2. Check `_project_specs/todos/active.md`
3. Review recent `decisions.md` entries if needed
4. Continue from "Next Steps"
### Session End Protocol
Before ending or when context limit approaches:
1. Create archive: `_project_specs/session/archive/YYYY-MM-DD.md`
2. Update current-state.md with handoff format
3. Ensure next steps are specific and actionable
| Trigger | Action |
|---|---|
| ~50+ tool calls | Summarize progress, archive verbose notes |
| Major feature complete | Archive feature details, update landmarks |
| Context shift | Summarize previous context, archive, start fresh |
| End of session | Full session handoff with archive |
Keep in active context:
Archive/summarize:
When compressing, use this format:
## Compressed Context - [Topic]
**Summary**: [1-2 sentences]
**Key Findings**:
- [Bullet points of important discoveries]
**Decisions Made**:
- [Reference to decisions.md entries]
**Relevant Code**:
- [File:line references]
**Archived Details**: [Link to archive file if created]
After significant work or at session end, create archive:
_project_specs/session/archive/YYYY-MM-DD[-topic].md
# Session Archive: [Date] - [Topic]
## Summary
[Paragraph summarizing what was accomplished]
## Tasks Completed
- [TODO-XXX] Description - Done
- [TODO-YYY] Description - Done
## Key Decisions
- [Reference decisions.md entries made this session]
## Code Changes
| File | Change Type | Description |
|------|-------------|-------------|
| src/auth/login.ts | Created | Login endpoint |
| src/auth/types.ts | Modified | Added RefreshToken type |
## Tests Added
- tests/auth/login.test.ts - Login flow tests
- tests/auth/refresh.test.ts - Token refresh tests
## Open Items Carried Forward
- [Anything not finished, now in active.md]
## Session Stats
- Duration: ~3 hours
- Tool calls: ~120
- Files modified: 8
- Tests added: 12
In active todos, reference session context:
## [TODO-042] Implement token refresh
**Status:** in-progress
**Session Context:** See current-state.md
### Progress Notes
- 2025-01-15: Started implementation, base structure done
- 2025-01-15: Added rotation logic, need error handling
When completing a todo:
Add to project scripts or aliases:
# Show current session state
alias session-status="cat _project_specs/session/current-state.md"
# Quick edit session state
alias session-edit="$EDITOR _project_specs/session/current-state.md"
# View recent decisions
alias decisions="tail -100 _project_specs/session/decisions.md"
# Create session archive
session-archive() {
cp _project_specs/session/current-state.md \
"_project_specs/session/archive/$(date +%Y-%m-%d).md"
echo "Archived to _project_specs/session/archive/$(date +%Y-%m-%d).md"
}
CLAUDE.md must reference session-management.md in the Skills section. Claude reads CLAUDE.md first, which directs it to follow session rules.
Include enforcement reminders in session file headers:
current-state.md header:
<!--
CHECKPOINT RULES (from session-management.md):
- Quick update: After any todo completion
- Full checkpoint: After ~20 tool calls or decisions
- Archive: End of session or major feature complete
-->
After completing any task, Claude should ask:
□ Did I make a decision? → Log it
□ Did this take >10 tool calls? → Full checkpoint
□ Is a feature complete? → Archive
□ Am I ending/switching context? → Archive + handoff
When starting a session, Claude must:
current-state.md exists and read itEvery ~20 tool calls, Claude should check:
Users can enforce by asking:
Task completed?
│
├── Decision made? ──────────────────→ Log to decisions.md
│
├── >10 tool calls OR significant? ──→ Full Checkpoint
│
├── Major feature done? ─────────────→ Archive
│
└── Otherwise ───────────────────────→ Quick Update
| File | Update Frequency | Purpose |
|---|---|---|
| current-state.md | Every task | Live state, next steps |
| decisions.md | When deciding | Architectural choices |
| code-landmarks.md | When patterns change | Code navigation |
| archive/*.md | End of session/feature | Historical record |
Weekly Installs
77
Repository
GitHub Stars
531
First Seen
Jan 20, 2026
Security Audits
Gen Agent Trust HubPassSocketPassSnykPass
Installed on
claude-code61
gemini-cli59
opencode59
codex53
cursor52
antigravity50
React 组合模式指南:Vercel 组件架构最佳实践,提升代码可维护性
116,600 周安装
arch-tsdown-cli:TypeScript CLI项目启动模板,支持ESM、d.ts自动生成与npm可信发布
95 周安装
Confluence 专家指南:空间管理、文档架构、模板与协作知识库搭建
96 周安装
构建完整AI聊天应用指南:Next.js + Neon + AI SDK实现持久化聊天与自动命名
96 周安装
员工手册AI助手:快速解答公司政策、福利、流程问题,提升HR效率
96 周安装
Auth0 Nuxt SDK:Nuxt 3/4 服务端会话认证完整指南
96 周安装
Svelte 5 Runes 静态站点构建指南:避免水合错误,适配 adapter-static
96 周安装