save-context

name	save-context
description	手动或自动保存会话核心内容到 context 文件。 触发方式：用户输入 /save-context，或首次工具调用时自动触发。 保存位置：.ai/context.md（主文件/索引）+ .ai/context-YYYY-MM-DD.md（日期归档/详细内容） 核心功能：记录历史错误与经验教训，避免模型切换后重复犯错。
triggers	["/save-context","自动检测：首次工具调用时保存项目结构"]

保存上下文到 Context 文件

Overview

手动或自动触发 skill，将会话核心内容保存到项目根目录 .ai/ 目录下的 context 文件中。

核心目的：当模型切换上下文后，重新开发新功能时不能重复已经犯过的错误。

文件分工：

• .ai/context.md - 主文件，记录索引（归档文件路径），不重复详细内容
• .ai/context-YYYY-MM-DD.md - 日期归档文件，记录当日所有详细内容

支持两种触发模式：

• 手动触发：用户输入 /save-context
• 自动触发：首次工具调用时自动保存项目结构

触发条件

手动触发

• 用户输入 /save-context
• 用户输入 save-context skill 命令

自动触发（首次工具调用时）

通过 PostToolUse Hook 实现：

1. 用户首次执行任何工具（Bash/Read/Edit/Write/Glob/Grep）
2. 检查 .ai/.context-initialized 标记文件是否存在
3. 如不存在，执行本 skill 保存项目结构
4. 创建标记文件防止重复保存

支持的触发格式

输入格式	触发方式	保存位置
/save-context	手动	.ai/context.md（索引）+ .ai/context-YYYY-MM-DD.md（详细内容）
首次工具调用	自动	.ai/context.md + .ai/context-YYYY-MM-DD.md

Core Actions

1. 检查初始化标记

// 检查 .ai/.context-initialized 是否存在
// 如不存在，说明是首次触发，需要保存项目结构

2. 分析会话内容

分析当前对话历史，识别核心内容：

1. 读取项目背景

   • 读取 .ai/context.md（如存在）了解已有重点
   • 读取最新的归档文件了解近期内容
   • 识别已有重点类型和模块

2. 分析对话，识别核心内容

   • 历史错误：对话中出现的错误、异常、失败
   • 问题与解决方案：用户提出的问题及解决过程
   • 架构决策：技术选型、设计模式等
   • 技术规范：API、Auth、Database 等
   • 项目结构：目录变化、文件新增

3. 提炼核心要点

   • 提取错误模式及经验教训
   • 提取问题描述和解决方案
   • 总结关键技术决策
   • 过滤临时性、过于细节的内容
   • 转换为正式的技术描述

3. 确定目标文件

1. 获取当前项目的根目录路径
2. 检查 .ai 目录是否存在，不存在则创建
3. 目标文件：
   • .ai/context.md（主文件/索引）
   • .ai/context-YYYY-MM-DD.md（日期归档/详细内容）

4. 读取或创建文件

如果文件不存在，创建新文件并写入标题：

# 项目重点

## 索引

### 历史错误记录
### 问题与解决方案
### 项目结构

## {日期}

5. 写入内容

日期归档文件 (.ai/context-YYYY-MM-DD.md) 写入详细内容：

# 项目重点 - {日期}

> 本文件为自动归档，保存当日所有重点内容

### 历史错误记录
- [Error][状态] 错误标题
  - **错误现象**：具体表现，日志/错误信息
  - **错误位置**：在哪个模块/文件/函数
  - **RootCause** 根本原因：
  - **Fix** 修复方法：
  - **Lesson** 经验教训：
  - **Avoid** 避免方法：

### 问题与解决方案
- [Question][状态] 问题标题
  - **问题描述**：详细描述问题
  - **Solution** 解决方案：
  - **Result** 结果：✅/❌

### 关键决策
- [Decision] 决策内容及理由

主文件 (.ai/context.md) 写入索引（不重复内容）：

# 项目重点

## 索引

### 历史错误记录
- 详见 [.ai/context-YYYY-MM-DD.md](.ai/context-YYYY-MM-DD.md) - YYYY-MM-DD

### 问题与解决方案
- 详见 [.ai/context-YYYY-MM-DD.md](.ai/context-YYYY-MM-DD.md) - YYYY-MM-DD

## {日期}

### 项目结构
- {目录/文件结构概览}

### 架构决策
- [Architecture] {决策内容}

6. 创建初始化标记

自动触发时，创建 .ai/.context-initialized 标记文件：

# Context 初始化标记
# 本文件用于标记项目结构已保存，防止重复保存
initialized: true
initialized_at: YYYY-MM-DD

文件格式示例

主文件 - .ai/context.md

# 项目重点

## 索引

### 历史错误记录
- 详见 [.ai/context-2026-04-03.md](.ai/context-2026-04-03.md) - 2026-04-03

### 问题与解决方案
- 详见 [.ai/context-2026-04-03.md](.ai/context-2026-04-03.md) - 2026-04-03
- 详见 [.ai/context-2026-04-01.md](.ai/context-2026-04-01.md) - 2026-04-01

## 2026-04-03

### 项目结构
- skills/ - 技能定义目录（包含各技能的 SKILL.md）
- commands/ - 命令定义目录
- .ai/ - AI上下文存储目录
- 根目录包含 CLAUDE.md 等配置文件

### 架构决策
- [Architecture] 采用多模块结构组织技能和命令
- [Architecture] 技能和命令支持多语言（-en.md, -zh.md）

## 2026-03-17

### 项目结构
- 每个命令/技能需要创建 3 个文件

日期归档 - .ai/context-2026-04-03.md

# 项目重点 - 2026-04-03

> 本文件为自动归档，保存当日所有重点内容

### 历史错误记录

- [Error][已修复] 在 save-context skill 中缺少错误记录功能
  - **错误现象**：模型切换上下文后，相同的错误反复出现
  - **错误位置**：skills/save-context/SKILL.md
  - **RootCause** 根本原因：
    - 原设计只记录架构决策，未记录错误模式
    - 缺少错误经验的结构化存储机制
  - **Fix** 修复方法：
    - 新增 [Error]、[RootCause]、[Fix]、[Lesson]、[Avoid] 标签
    - 设计错误记录的标准化格式
    - 修改文件分工：主文件只记录索引，归档文件记录详细内容
  - **Lesson** 经验教训：
    - 模型切换后无法继承历史错误记忆
    - 需要显式记录错误模式供后续参考
  - **Avoid** 避免方法：
    - 每次发现错误时，立即记录到 context 文件
    - 新会话开始时先读取历史错误记录

### 问题与解决方案

- [Question][已解决] 用户提出如何记录问题和解决方案
  - **问题描述**：用户需要详细记录问题及解决过程，避免重复犯错
  - **Solution** 解决方案：
    - 设计结构化标签系统区分不同类型内容
    - 使用日期归档文件存储详细内容
    - 主文件只记录索引便于快速浏览
  - **Result** 结果：✅ 已解决 - 成功添加了错误记录功能

### 关键决策

- [Decision] 采用索引 + 详细内容分离存储
  - 主文件只记录归档文件路径，不重复内容
  - 新会话可通过索引快速定位历史记录
  - 避免内容重复和维护负担

初始化标记 - .ai/.context-initialized

# Context 初始化标记
# 本文件用于标记项目结构已保存，防止重复保存
initialized: true
initialized_at: 2026-04-03

实现步骤

手动触发 (/save-context)

1. 读取现有 .ai/context.md 了解项目背景
2. 读取最新归档文件了解近期内容
3. 分析当前对话历史，提取错误、问题、决策等核心内容
4. 生成预览内容（显示将写入归档文件的详细内容 + 主文件的索引更新）
5. 等待用户确认
6. 写入 .ai/context-YYYY-MM-DD.md（详细内容）
7. 更新 .ai/context.md（索引）
8. 告知用户保存结果

自动触发（首次工具调用）

1. PostToolUse Hook 检测到工具执行
2. 检查 .ai/.context-initialized 是否存在
3. 如不存在，执行以下步骤：
   • 扫描项目结构
   • 生成项目结构概述
   • 写入 .ai/context-YYYY-MM-DD.md
   • 更新 .ai/context.md（添加索引）
   • 创建 .ai/.context-initialized 标记文件
4. 不询问用户，直接保存

确认机制

自动触发时

不询问用户，直接保存（无打扰）

手动触发时

展示预览，等待确认：

📝 即将保存以下内容：

【.ai/context-2026-04-03.md】（详细内容）

### 历史错误记录
- [Error][已修复] 错误描述
  - 错误现象：...
  - 错误位置：...
  - RootCause: ...
  - Fix: ...
  - Lesson: ...
  - Avoid: ...

### 问题与解决方案
- [Question][已解决] 问题描述
  - 问题描述：...
  - Solution: ...
  - Result: ...

【.ai/context.md】（索引更新）

### 历史错误记录
- 详见 [.ai/context-2026-04-03.md](.ai/context-2026-04-03.md) - 2026-04-03

### 问题与解决方案
- 详见 [.ai/context-2026-04-03.md](.ai/context-2026-04-03.md) - 2026-04-03

确认请回复"确认"或"y"，取消请回复"取消"或"n"

错误处理

• 如果无法创建目录，提示用户检查权限
• 如果无法写入文件，提示用户检查文件权限
• 如果是自动触发且失败，记录错误但不打扰用户

内容分类标签

通用标签

标签	含义
[Question]	用户提出的问题或需求
[Solution]	解决方案及决策过程
[Decision]	关键决策点及理由
[Issue]	发现的问题或 Bug
[Result]	结果说明

错误记录核心标签

标签	含义
[Error]	曾经犯过的错误
[RootCause]	错误根本原因分析
[Fix]	错误修复方法
[Lesson]	经验教训
[Avoid]	如何避免同类错误

状态标签

状态	含义
[待解决]	问题已记录，待处理
[进行中]	正在解决
[已解决]	问题已解决
[已修复]	错误已修复
[已搁置]	暂时搁置

最佳实践

首次保存（自动触发）

当首次工具调用触发时，保存项目结构概述：

### 项目结构
- skills/ - 技能定义目录
- commands/ - 命令定义目录
- .ai/ - AI上下文存储目录
- 根目录包含 CLAUDE.md 等配置文件

后续保存（手动触发）

用户通过 /save-context 手动触发时：

1. 识别错误模式：

   • 注意对话中的错误信息（Exception、Error、失败）
   • 识别导致错误的原因分析
   • 记录修复方法和经验教训

2. 问题与解决方案记录：

   ### 问题与解决方案
   - [Question][进行中] 问题描述
     - **问题描述**：详细描述问题
     - **Solution** 解决方案：
       - **方案设计**：详细的解决思路
       - **备选方案**：考虑过哪些其他方案
       - **实施步骤**：具体的操作步骤
     - **Result** 结果：✅/❌
   

3. 历史错误记录：

   ### 历史错误记录
   - [Error][已修复] 错误标题
     - **错误现象**：具体表现
     - **错误位置**：模块/文件/函数
     - **RootCause** 根本原因：
     - **Fix** 修复方法：
     - **Lesson** 经验教训：
     - **Avoid** 避免方法：
   

核心原则

每次发现错误立即记录：

• 错误是宝贵的学习机会
• 记录错误可以避免未来重蹈覆辙
• 模型切换后可通过 context 文件继承错误经验

新会话开始时：

• 先读取 .ai/context.md 了解项目索引
• 根据索引查看历史错误记录
• 避免在新功能开发中重复犯错