🧩 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 <AI_BOOTSTRAP_BLOCK> 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_BOOTSTRAP_BLOCK> 作为第一条消息， 新的 AI 便能从你上次中断的精确位置无缝接续 —— 无需重新解释背景，零上下文损耗。

---

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

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

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

维度Claude 内置 MemoryAI_CONTEXT.md（本 Skill）文件位置~/.claude/（隐藏目录）./（项目根目录，与代码并排）可见性只有 Claude Code 能读人和任何 AI 工具都能读格式Claude 自由决定，不固定固定五章节结构，格式可预期Git 追踪❌ 无法追踪、无法 diff✅ 可提交、可审查、可回滚跨工具使用❌ 绑定 Claude Code✅ 可粘贴给 Cursor、GPT-4、Gemini 等任意 AI团队共享❌ 个人私有，队友不可见✅ git pull 即可获得完整上下文自愈能力❌ 不检查代码现实，可能记录过时内容✅ 每次与代码对比，自动修正陈旧描述Bootstrap Block❌ 无✅ <120 token 的冷启动指令，跨会话零损耗恢复

两者可以共存 / They complement each other#

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

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

---

✨ Key Features / 核心特性#

Feature说明🔍 Environment Scan自动扫描技术栈、目录结构、Git 历史🩹 Self-Healing检测并剔除与当前代码矛盾的陈旧文档内容，代码即真相⚡ Bootstrap Block生成 <120 token 的高熵 AI 启动指令，用于冷启动新会话🎛 Parameterizable支持 optimizeFor / autoRepair / compress / silent 标志🌐 VCS-agnostic有 Git 时用 Git，无 Git 时优雅降级

---

🚀 Installation / 安装#

Claude Code#

bash

# 将 .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)#

text

# 中文 — 明确指定 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 工具拦截：

text

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

---

📤 Cross-session resume / 跨会话恢复#

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

text

# 粘贴到新会话的第一条消息 / 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 包含五个标准章节：

text

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

---

⚙️ Parameters / 参数说明#

参数默认值说明optimizeFor=performance``detail仅保留状态类章节（2、4、5），省略架构描述autoRepair=false``true关闭陈旧内容自愈，保留原文档compress=false``true不生成 <AI_BOOTSTRAP_BLOCK>``silent=true``false执行后只输出一行成功提示fileName=custom.md``AI_CONTEXT.md写入指定文件名

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

---

🔒 Self-Healing Rules / 自愈规则#

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

冲突类型处理规则文档提到的文件已被删除移除引用，添加 ~~删除线~~ 注记函数 / 类已改名以代码中的实际名称覆盖文档架构描述与目录结构矛盾以当前目录结构为准重写"下一步"任务已在 Git 中提交标记 [x] DONE，移至 Recent Diff

---

🔐 Security Notice / 安全提示#

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

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

风险类型说明建议操作🔑 API Keys / 密钥Bootstrap Block 可能从 .env、配置文件或近期对话中捕获敏感字串提交前运行 git diff 检查，或使用 git-secrets / trufflehog 扫描🗝 Tokens / 令牌Git 历史摘要中可能含有带 token 的 commit message确认 Recent Diff 章节中无明文凭证📁 私有路径内部服务器地址、数据库连接串可能出现在架构描述中若文件需公开共享，手动脱敏后再提交💬 会话内容Intent Extraction 阶段会摘录最近对话，可能含有业务敏感信息在开放仓库中使用时，优先使用 compress=false 或 silent=true 精简输出

推荐做法 / Recommended practice：

bash

# 提交前快速扫描 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). 依次运行以下命令，命令不存在时静默跳过。

bash

# 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:

Conflict TypeResolution RuleFile mentioned in doc no longer existsRemove reference, add ~~strikethrough~~ noteFunction/class renamed in codeUpdate doc to match code — code winsArchitecture claim contradicts directory structureOverwrite with current realityStale "Next Steps" that are now committedMark [x] DONE and move to Recent Diff

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:

bash

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

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

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

---

Standard Output Structure#

markdown

<!-- AI_CONTEXT_ANCHOR v1 | Last Synced: $ISO_DATETIME | Node: $LOCATION -->

# 🧩 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

text

**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

<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]
</AI_BOOTSTRAP_BLOCK>

---

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

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

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 最应打开的文件 + 函数位置，编码为单行指令：

text

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:

bash

# 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 / 参数与行为标志#

Parameter / 参数Default / 默认Effect / 效果optimizeFor=performance``detail仅保留章节 2、4、5，省略架构和决策描述autoRepair=false``true跳过陈旧内容移除，保留原文档compress=false``true不生成 <AI_BOOTSTRAP_BLOCK>``silent=true``false写入后仅输出一行成功提示fileName=custom.md``AI_CONTEXT.md写入指定文件名

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

---

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

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

text

✅ 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 <AI_BOOTSTRAP_BLOCK> 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 模式。