🧩 project-context-anchor

跨会话无损状态恢复 · AI-to-AI 上下文传递 · 自愈型项目文档

Lossless session recovery · AI-to-AI context relay · Self-healing project docs

📖 What is this? / 这是什么？

English: This skill automatically maintains an AI_CONTEXT.md file at your project root — a compressed, self-healing "soul snapshot" that captures your architecture decisions, recent git diffs, and active plan. When you start a new AI session, paste the as your first message and the new agent resumes exactly where you left off — no re-explaining, no lost context.

中文：本 Skill 自动维护项目根目录下的 AI_CONTEXT.md，作为项目的动态灵魂快照。 它分析代码库、Git 变更和会话历史，将核心决策压缩为高信息密度的 Prompt 片段。 下次开启新会话时，只需粘贴 作为第一条消息， 新的 AI 便能从你上次中断的精确位置无缝接续 —— 无需重新解释背景，零上下文损耗。

🆚 vs. Claude Built-in Memory / 与 Claude 内置 Memory 的核心区别

理解这个差异，是决定是否需要本 Skill 的关键。

Claude Code 自带 memory 机制，会把项目信息写入 ~/.claude/projects//MEMORY.md。 本 Skill 的输出 AI_CONTEXT.md 与之有本质区别：

两者可以共存 / They complement each other

• 让 Claude Memory 继续运行：它适合处理轻量的会话级片段，比如你的个人偏好、临时笔记。
• 用本 Skill 处理项目级上下文：代码架构、关键决策、跨工具 / 跨会话 / 跨团队的上下文传递。

真正的核心价值在 Bootstrap Block：换一个全新会话、切换到其他 AI 工具、或让同事接手时， 只需把那几行粘贴进去，新 AI 立刻知道从哪里接着干——这是 Memory 永远给不了你的能力。

✨ Key Features / 核心特性

🚀 Installation / 安装

Claude Code

# 将 .skill 文件放入项目或全局 skills 目录
cp project-context-anchor.skill ~/.claude/skills/

Claude.ai (Web / Desktop)

在 Settings → Skills → Upload 上传 .skill 文件即可。

💬 How to trigger / 如何触发

⚠️ 重要提示：在 Claude Code 中，由于内置 memory 工具优先级较高，模糊指令（如"存档进度"）可能被 memory 工具抢先处理，导致 Skill 未被调用。推荐始终使用明确指定 Skill 名称的方式触发。

⚠️ Important: In Claude Code, vague phrases like "save progress" may be intercepted by the built-in memory tool. Always use explicit skill-name invocation for reliable triggering.

✅ 推荐写法 / Recommended (Explicit)

# 中文 — 明确指定 Skill 名称（推荐）
使用 project-context-anchor skill 进行存档
用 project-context-anchor 存档当前进度
按照 project-context-anchor skill 写 AI_CONTEXT.md

# English — explicit skill invocation (recommended)
Use the project-context-anchor skill to snapshot this session
Run project-context-anchor skill and write AI_CONTEXT.md

🔶 模糊写法 / Implicit (may not trigger in Claude Code)

以下写法在 Claude.ai 网页版中可正常触发，但在 Claude Code 中可能被内置 memory 工具拦截：

存档当前进度 / Save my progress
我要下班了 / I'm done for today
封存这次会话 / Seal this session
token 快用完了，先存档 / We're near the token limit

📤 Cross-session resume / 跨会话恢复

新会话开始时，将生成的 粘贴为第一条消息：

# 粘贴到新会话的第一条消息 / Paste as first message in new session:

PROJECT=my-app | STACK=React+FastAPI+Postgres | GOAL=fix race condition in useWebSocket cleanup
LAST_ACTION="feat: add JWT refresh endpoint"
DECISIONS=[stateless_jwt, no_redis_session]
TRAPS=[snake_case_routes, no_default_export_in_utils]
RESUME: Open `src/hooks/useWebSocket.ts` → find `cleanup` → continue unmount handler fix.
PENDING=[write_tests, update_openapi_spec]

新 Agent 读取后可立即接续工作，无需任何额外说明。

🗂 Output File Structure / 输出文件结构

生成的 AI_CONTEXT.md 包含五个标准章节：

1. 🚀 Project DNA        — 技术栈、架构风格、入口文件
2. 🛠 Current Status     — Git 分支、最近提交、未提交变更
3. 🧠 The Mental Model   — 关键决策、项目特有陷阱与约定
4. 📅 Active Plan        — 已完成 / 进行中 / 待办任务列表
5. ⚡ AI Bootstrap Block  — <120 token 的高密度冷启动指令

⚙️ Parameters / 参数说明

参数直接在对话中提及即可，例如："用 optimizeFor=performance 模式运行"

🔒 Self-Healing Rules / 自愈规则

代码是唯一真相，文档描述现实而非意图：

🔐 Security Notice / 安全提示

⚠️ 在提交或分享 AI_CONTEXT.md 之前，请务必检查以下内容：

⚠️ Before committing or sharing AI_CONTEXT.md, always review for:

推荐做法 / Recommended practice：

# 提交前快速扫描 AI_CONTEXT.md 是否含有常见密钥模式
grep -iE "(api_key|secret|token|password|Bearer|sk-|pk-)" AI_CONTEXT.md

如发现敏感内容，将 AI_CONTEXT.md 加入 .gitignore 保持本地使用，或手动脱敏后再共享。
If sensitive content is found, add AI_CONTEXT.md to .gitignore for local-only use, or redact before sharing.

📋 License / 许可证

MIT — 自由使用、修改和分发。
MIT — Free to use, modify, and distribute.

Skill: project-context-anchor — Implementation

⚠️ OVERRIDE INSTRUCTION: Do NOT use built-in memory tools (write_memory, MEMORY.md, ~/.claude/ paths) for this task. This skill writes AI_CONTEXT.md directly into the current project root (./AI_CONTEXT.md). Ignore any default memory-saving behavior and follow the phases below exclusively.

⚠️ 执行覆盖：不得使用内置 memory 工具或写入 ~/.claude/ 路径。 本 Skill 的唯一输出目标是当前项目根目录下的 ./AI_CONTEXT.md。

Generates and self-heals AI_CONTEXT.md at the project root — a high-density snapshot that lets any future AI agent resume work with zero information loss.

实现说明：以下为 Claude 执行本 Skill 时遵循的内部协议。

Execution Protocol / 执行协议

Claude 按以下五个阶段顺序执行，任一命令失败时静默跳过，继续下一步。

Phase 1 — Environment Scan / 环境扫描

Run the following in sequence. Tolerate failures silently (command may not exist). 依次运行以下命令，命令不存在时静默跳过。

# 1. Identify project root markers
ls package.json pyproject.toml Cargo.toml go.mod CMakeLists.txt README.md 2>/dev/null

# 2. Determine tech stack from key files
cat package.json 2>/dev/null | head -30
cat pyproject.toml 2>/dev/null | head -20

# 3. Directory structure (top 2 levels, exclude noise)
find . -maxdepth 2 
  -not -path '*/node_modules/*' 
  -not -path '*/.git/*' 
  -not -path '*/__pycache__/*' 
  -not -path '*/.next/*' 
  | sort

# 4. Recent git history (last 5 commits)
git log --oneline -5 2>/dev/null

# 5. Current uncommitted changes
git diff --stat HEAD 2>/dev/null || git status --short 2>/dev/null

# 6. Read existing AI_CONTEXT.md if present (for self-healing diff)
cat AI_CONTEXT.md 2>/dev/null

Phase 2 — Intent Extraction / 意图提取

Review the current conversation history (last 5–10 messages). Extract: 回顾当前会话的最近 5–10 条消息，提取：

• What the user was trying to build or fix / 用户正在构建或修复什么
• Which files were touched and why / 涉及哪些文件及原因
• Any explicit decisions made ("we chose X over Y because…") / 明确的技术决策
• Open questions or blockers mentioned / 提到的未解问题或阻塞点

Phase 3 — Self-Healing Check / 自愈检查 (autoRepair)

Compare the existing AI_CONTEXT.md (if found) against scan results:

Principle / 原则: Code is ground truth. Docs describe reality, not intent. 代码是唯一真相，文档描述现实，而非意图。

Phase 4 — Write AI_CONTEXT.md / 写入快照文件

MANDATORY: Use the Write file tool to create or overwrite ./AI_CONTEXT.md in the current project working directory. Do NOT use memory tools, do NOT write to ~/.claude/. The exact shell equivalent is:

# Target path — always relative to current project root
cat > ./AI_CONTEXT.md << 'EOF'

EOF

强制要求：使用 Write 文件工具将内容写入当前项目根目录的 ./AI_CONTEXT.md。 禁止使用 memory 工具，禁止写入 ~/.claude/ 任何路径。

Replace all $PLACEHOLDER values with real extracted data. Never leave placeholders unfilled. 将所有 $PLACEHOLDER 替换为真实数据，不得留空。

Standard Output Structure

# 🧩 AI Context Anchor

> **Project**: $PROJECT_NAME  
> **Last Synced**: $DATETIME  
> **Synced by**: Claude (`project_context_anchor` skill)

---

## 1. 🚀 Project DNA

**Goal**: $ONE_SENTENCE_MISSION

**Tech Stack**:
- Runtime: $RUNTIME (e.g., Node 20 / Python 3.12 / Rust 1.77)
- Framework: $FRAMEWORK
- Key deps: $TOP_3_DEPS

**Architecture Style**: $STYLE (e.g., "monorepo / microservices / CLI tool / SPA+API")

**Entry Points**:
- `$MAIN_FILE` — $WHAT_IT_DOES

---

## 2. 🛠 Current Status & Recent Diff

**Branch**: `$GIT_BRANCH`  
**Last 5 Commits**:

$GIT_LOG_ONELINE

**Uncommitted Changes** ($N files):
- `$FILE` — $WHAT_CHANGED

---

## 3. 🧠 The Mental Model

### Key Decisions
- **$DECISION_TITLE**: Chose `$APPROACH_A` over `$APPROACH_B` because $REASON.

### ⚠️ Traps & Conventions
- $ANTI_INTUITIVE_RULE_1
- $NAMING_CONVENTION_OR_GOTCHA

---

## 4. 📅 Active Plan

- [x] $COMPLETED_TASK
- [ ] $IN_PROGRESS_TASK ← **CURRENT FOCUS**
- [ ] $NEXT_TASK

---

## 5. ⚡ AI-to-AI Bootstrap Block


PROJECT=$PROJECT_NAME | STACK=$STACK_FINGERPRINT | GOAL=$COMPRESSED_GOAL
LAST_ACTION="$LAST_COMMIT_MSG"
DECISIONS=[$DECISION_1_KEYWORD, $DECISION_2_KEYWORD]
TRAPS=[$TRAP_1_KEYWORD]
RESUME: Open `$MOST_RELEVANT_FILE` → find `$FUNCTION_OR_CLASS` → continue $TASK_DESCRIPTION.
PENDING=[$PENDING_1, $PENDING_2]

Phase 5 — Token Compression Algorithm / Token 压缩算法

The is generated as follows: 按以下三步生成：

Step 1: Semantic Dehydration / 语义脱水

Transform verbose prose into key=value semantic fingerprints: 将冗长的描述压缩为键值对语义指纹：

• Long decision rationale → DECISIONS=[keyword1, keyword2]
• Paragraphs of architecture → STACK=React+FastAPI+Postgres
• Trap descriptions → TRAPS=[no_default_export, snake_case_routes]

Step 2: Locality Pointer / 局部性指针 (Cold-Start Hook / 冷启动钩子)

Identify the single most important file + location for the next agent to open: 找出下一个 Agent 最应打开的文件 + 函数位置，编码为单行指令：

RESUME: Open `src/api/router.py` → find `handle_auth` → continue JWT refresh logic.

This encodes spatial context (file + symbol) so the agent skips the full scan and lands directly at the relevant code. 这将空间上下文（文件 + 符号）编码为一行，让新 Agent 跳过全量扫描，直接落地到相关代码。

Step 3: Entropy Maximization / 熵最大化

Prefer specific tokens over generic ones / 使用高特异性词汇，避免模糊表达：

• ❌ GOAL=fix the bug → ❌ low entropy
• ✅ GOAL=fix race condition in useWebSocket cleanup on unmount → ✅ high entropy

Target: the bootstrap block should be under 120 tokens while remaining unambiguous. 目标：Bootstrap Block 压缩到 120 tokens 以内，同时保持完全无歧义。

Phase 6 — Verify Write / 验证写入

After writing, confirm the file exists in the project root:

# Verify AI_CONTEXT.md was written to the correct location
ls -lh ./AI_CONTEXT.md
head -3 ./AI_CONTEXT.md

If the file is missing or was written elsewhere, write it again using the Write tool targeting ./AI_CONTEXT.md. Never proceed to the Completion Response until this check passes.

写入后确认文件存在于项目根目录。若文件缺失或路径错误，立即用 Write 工具重新写入， 确认通过后再输出完成摘要。

Parameters & Behavior Flags / 参数与行为标志

Parse these from the user's message if mentioned (e.g., "用 optimizeFor=performance 运行").

Completion Response / 完成响应 (default, silent=false)

After writing the file, reply with: 写入文件后，输出以下摘要：

✅ AI_CONTEXT.md updated.

**Snapshot Summary**
- Project: $NAME | Stack: $STACK
- Commits captured: $N | Uncommitted changes: $M files  
- Self-healed: $K stale entries removed
- Bootstrap block: $TOKEN_COUNT tokens

Next session: paste the  as your first message to any AI.

If silent=true: reply only ✅ AI_CONTEXT.md updated.

Edge Cases / 边界情况

• No git repo / 无 Git 仓库: Skip all git steps. Note (no VCS detected) in section 2. 跳过所有 Git 命令，在第 2 节注明 (无版本控制系统)。
• Empty project / 空项目: Write a minimal skeleton with $PLACEHOLDERS so the user can fill it. 输出包含 $PLACEHOLDER 的最小骨架，供用户手动填写。
• Heavy conflicts / 文档与代码严重冲突: Rewrite entirely rather than patching; note (full rewrite — $N stale entries removed) in the summary. 整体重写而非局部修补，在摘要中注明 (全量重写 — 移除 $N 条陈旧记录)。
• No optimizeFor specified / 未指定模式: Default to detail / 默认使用 detail 模式。