告别AI健忘症：构建Claude Code项目记忆系统，每年节省26小时开发时间发光的神经网络“大脑”连接到悬浮的文档图标，代表包含 bugs、decisions、configuration files 的项目记忆，便于快速 recall。

一个不到 300 行的 skill，如何变成我最常用的 AI 辅助开发效率工具

想象一下：周二晚上 11 点。你盯着一个似曾相识的报错信息—— “Connection refused on port 5432” 。你以前见过它，也解决过它。但在哪里？什么时候？提交说明只写了“fixed db connection”。Stack Overflow 给出了十二种答案。你的 AI 助手热情地给出你已经试过的方案。

这就是所谓的“AI 健忘症”（AI amnesia），而它带来的成本远超你的想象。

每个 AI 编码助手都有同一个令人沮丧的限制：在会话之间它们什么都记不住。开启一个新对话，Claude 并不知道你昨天花了 45 分钟才发现：你们的 staging 环境用的是 5433 端口，而不是 5432。它不记得你为什么选了 PostgreSQL 而不是 MongoDB（因为团队已有相关经验）。它也想不起来“connection refused”几乎总意味着 VPN 断了。或者它会突然用一个新的 NLP lib 或 charting lib，而整个项目其实已经统一在用另一套，而且你早就决定好了。然后——你只能再次解释。一次又一次。

那些好不容易积累的知识？每次都会消失。

我在看一个关于如何让 Claude Code 保持项目上下文更新的 YouTube 视频时，发现了一个简单的解决方法。作者在 CLAUDE.md 里链接了一些小的 markdown 文件来追踪 decisions、bugs 和关键事实。那一刻我灵光一闪： 如果我写一个 skill 来自动化管理这些呢？

这个想法就成了 project-memory ，这是我为 Claude Code 写的最早的 skills 之一。尽管非常简单（不到 300 行），它实实在在为我省下了很多很多时间。这个教程会教你如何构建你自己的项目记忆 skill，更重要的是，如何思考并打造能真正解决问题的 skills。

如今可不止 Claude Code 一家。Codex、GitHub Copilot 和 OpenCode 都宣布支持 Agentic Skills。甚至还有一个支持 Gemini、Aidr、Qwen Code、Kimi K2 Code、Cursor 等在内的 agentic skills 市场，已支持 14+ 平台，并有一个通用的 agentic skills 安装器（skilz）。在本指南中，我将交替使用“Claude”和“coding agent”这两个词，就像把“复印”说成“Xerox 一下”。（顺带一提，在我的日常工作流里，我更偏好 Claude Code、OpenCode 和 Gemini CLI。）

AI 健忘症的真实成本

让我来描绘一个你可能很熟悉的场景：

第 1 个月：首次发现

Error: CORS policy blocked request from localhost:3000
[调试 2 小时，尝试 proxy 配置、header 变更、nginx 重写]
Solution: 在 package.json 添加 proxy 配置

第 6 个月：似曾相识

Error: CORS policy blocked request from localhost:3000
Developer: "这看起来很眼熟……我们当时怎么修的？"
[翻提交记录、再看 Stack Overflow、问 Claude 但它全不记得]
[花了 1 小时重新发现还是那个 proxy 配置的解法]

耳熟吗？残酷的事实是：没有记忆的 AI 编码助手实际上让情况更糟而不是更好。没有记忆，就意味着：

每次新对话都从零开始
每个 bug 都像是第一次解决
解决方案被反复“重新发现”（我曾在 6 个月内四次解决同一个 CORS 问题）
没有学习在时间维度上积累，无论是你，还是你的 AI 助手

隐藏成本惊人。 如果你每周仅仅花 30 分钟在重复解决已经解决过的问题上，一年就是 26 小时。按每小时 100 美元算，每位开发者每年就浪费 2,600 美元。

但如果你的 AI 助手能记住呢？

什么是 Claude Code Agent Skill？

在深入 project-memory 之前，先弄清楚 skill 到底是什么。如果你曾希望教会 Claude 一个特定工作流，或赋予它领域知识，skills 就是答案。

一个 agent skill 就是一个包含 SKILL.md 文件和可选资源的文件夹。SKILL.md 有两部分：

YAML frontmatter ：元数据，告诉 Claude 何时激活该 skill
Markdown body ：skill 激活后，Claude 按此执行的指令

把 skills 当作可安装的“专家模式”。当你说“set up project memory”时，Claude 不需要猜你的意思。它会加载具体且经过验证的指令来完成这件事。

Agent Skill 结构剖析

告别AI健忘症：构建Claude Code项目记忆系统，每年节省26小时开发时间 SKILL.md 的文件结构：YAML frontmatter（name、description），Markdown 正文包含 Overview、When to Use、Core Capabilities、Examples、Success Criteria

SKILL.md 的结构展示了 YAML frontmatter（name 和 description），以及 Markdown 正文的各个部分：Overview、When to Use、Core Capabilities、Examples、Success Criteria。

Skills 通常有两个放置位置：

告别AI健忘症：构建Claude Code项目记忆系统，每年节省26小时开发时间

把常用 skills 放在用户主目录 ~/.claude/skills/，可在所有项目中全局使用，适合 code review、documentation 等通用 skills。项目特定的 skills 则放在项目根目录的 .claude/skills/，仅在本项目内可用，用于项目工作流、团队约定等。我说“通常”是因为还可能有企业级统一 skills、mono-repo 共享 skills 等；而且也取决于你使用的提供商（例如 ~/.codex/skills/、~/.config/opencode/skill/、~/.gemini/skills/、.claude/skills/、.codex/skills/、.opencode/skills/ 等）。

💡 试试这个：运行 ls ~/.claude/skills/ 看看你已经安装了哪些 skills。如果该目录还不存在，安装第一个 skill 时会自动创建。

Skill 激活如何运作

当你发出请求时，Claude Code 在加载 agentic skills 时遵循一种 progressive disclosure （渐进披露）模式：按需加载，只在需要时加载需要的内容。这既保持交互快速，又能按需提供强功能。

告别AI健忘症：构建Claude Code项目记忆系统，每年节省26小时开发时间 Skill 激活流程图：三阶段——Discovery（扫描目录、加载元数据）、Matching（请求与 skill 匹配）、Execution（加载 SKILL.md、按指令完成任务）

上图展示了 skill 激活流程：Discovery（扫描目录，仅读元数据）、Matching（检查请求是否匹配 skill）、Execution（加载 SKILL.md，按指令完成任务）。

关键点在于：Claude 会扫描 skill 目录并只读取元数据（name + description），直到找到匹配项才会加载完整指令。这意味着即使安装了几十个 skills，日常对话也不会变慢。

理解了机制后，我们来看看 project-memory 如何落地。

Project Memory Agent Skill

project-memory skill 会在 docs/project_notes/ 目录中创建一个结构化的知识系统，包含四个专用文件。每个文件都有其特定目的，用于保存和召回项目知识。

Memory 文件结构

告别AI健忘症：构建Claude Code项目记忆系统，每年节省26小时开发时间项目记忆的文件结构：docs/project_notes/ 目录下包含 bugs.md、decisions.md、key_facts.md、issues.md，以及 CLAUDE.md 和 AGENTS.md 两个配置文件

注意该结构：docs/project_notes/ 包含 bugs.md、decisions.md、key_facts.md、issues.md，并通过 CLAUDE.md 和 AGENTS.md 进行链接，共同组成项目记忆。

告别AI健忘症：构建Claude Code项目记忆系统，每年节省26小时开发时间

每个 memory 文件都有特定作用：
* bugs.md：作为可搜索的 bug 数据库。例如，条目“BUG-018: Pulumi state drift – run pulumi refresh – yes”会同时记录问题与解决方案，避免相同问题再次出现时的时间浪费。我用它来追踪项目中反复出现的问题。
* decisions.md：使用 ADR（架构决策记录）来记录架构选择，例如“ADR-012: Use D3.js for all charts (team expertise)”，以确保一致性并防止后续技术选择冲突。
* key_facts.md：用于快速查询重要的项目细节，比如 “Staging API: https://api.staging.example.com:8443”，避免端口和 URL 的猜测。
* issues.md：以时间顺序维护工作日志，比如“TICKET-456: Implemented user auth – 2024–01–15”，建立完成工作与具体工单和日期的对应关系。

下面我来分解这个 skill 的各个部分。

第 1 部分：Agent Skill 的 Frontmatter（它的“何时”）

“`yaml

name: project-memory
description: Setup and maintain a structured project memory system in docs/project_notes/ that tracks bugs with solutions, architectural decisions, key project facts, and work history. Use this skill when asked to “set up project memory”, “track our decisions”, “log a bug fix”, “update project memory”, or “initialize memory system”.

“`

description 字段至关重要，它告诉 Claude 何时激活。注意这里嵌入了具体的触发短语：“set up project memory”、“track our decisions”、“log a bug fix”。当你说出这些短语中的任意一个，Claude 就会识别并加载完整指令。（完整 skill 在文末给出。）

💡 试试这个：编写你自己的 skill 描述时，加入 3–5 个用户自然会说出来的短语。测试激活时多尝试变体：“help me track decisions”、“set up decision tracking”、“I want to log our architectural choices”。

第 2 部分：何时使用该 Agent Skill（上下文触发）

“`markdown

When to Use This Skill

Invoke this skill when:

Starting a new project that will accumulate knowledge over time
The project already has recurring bugs or decisions that should be documented
The user asks to “set up project memory” or “track our decisions”
Encountering a problem that feels familiar (“didn‘t we solve this before?”)
Before proposing an architectural change (check existing decisions first)
“`

这一节会强化触发条件，并帮助 Claude 理解更广泛的使用场景。“didn‘t we solve this before?” 这个短语尤其关键——它精准捕捉到记忆最能帮上忙的痛点时刻。

第 3 部分：初始设置指令（它的“做什么”）

“`markdown

Core Capabilities

1. Initial Setup – Create Memory Infrastructure

When invoked for the first time in a project, create the following structure:

docs/
└── project_notes/
├── bugs.md # Bug log with solutions
├── decisions.md # Architectural Decision Records
├── key_facts.md # Project configuration and constants
└── issues.md # Work log with ticket references

Directory naming rationale: Using docs/project_notes/ instead of memory/ makes it look like standard engineering organization, not AI-specific tooling.
“`

这个设计比看起来更重要：让记忆看起来像正常的文档 。如果你把文件放到 ai-memory/ 或 claude-context/，开发者就会把它当成 AI 工具，不愿维护。而放到 docs/project_notes/，它就像标准工程文档， 任何人 都能去更新，无论是否使用 AI 助手。

第 4 部分：Memory 条目格式（结构化知识）

该 skill 为每种条目定义了统一格式。保持一致很重要，因为即使在几个月后，Claude 也能稳定解析：

告别AI健忘症：构建Claude Code项目记忆系统，每年节省26小时开发时间上图展示了 bugs.md 与 decisions.md 的条目格式对比。bugs.md 采用 Issue、Root Cause、Solution、Prevention 结构，而 decisions.md 遵循 ADR 格式，包含 Context、Decision、Alternatives、Consequences。

其中 Prevention 字段尤其关键，它将“已修复的 bug”转化为“可传承的经验”。六个月后，Claude 甚至能在你遇到同类问题前发出预警。

第 5 部分：CLAUDE.md 的记忆协议（核心机制）

真正的威力在于此。通过配置 CLAUDE.md，可以让 Claude 默认具备“记忆意识”：

“`

2. Configure CLAUDE.md – Memory-Aware Behavior

Add or update the following section in the project’s CLAUDE.md file:

Project Memory System

Memory-Aware Protocols

Before proposing architectural changes:
– Check docs/project_notes/decisions.md for existing decisions
– Verify the proposed approach doesn’t conflict with past choices

When encountering errors or bugs:
– Search docs/project_notes/bugs.md for similar issues
– Apply known solutions if found
– Document new bugs and solutions when resolved

When looking up project configuration:
– Check docs/project_notes/key_facts.md for credentials, ports, URLs
– Prefer documented facts over assumptions
“`

关键在于，一旦这些协议写入 CLAUDE.md，Claude 在提出建议或做出决策前便会自动查阅记忆文件。你无需再特意提醒“检查 bug 日志”，这将成为其默认行为。

实战影响：知识的复利效应

以下通过具体案例，展示记忆系统如何改变日常开发工作流。

记忆驱动的 Bug 处理

告别AI健忘症：构建Claude Code项目记忆系统，每年节省26小时开发时间对比图：无记忆时修复 bug 需 45 分钟从头调试；有记忆时通过查询 bugs.md 仅需 5 分钟

如上图所示：没有记忆系统时，从头调试一个问题平均耗时 45 分钟；而借助 bugs.md 查询，解决时间可缩短至 5 分钟。这不仅是时间节省，更能避免不必要的挫败感。

示例 1：修复速度提升（真实数据）

场景：
10 月 20 日，部署时遇到 Pulumi state drift 错误，报错信息隐晦：error: update failed。经过 45 分钟的调试（检查 IAM 权限、回溯近期改动、尝试不同部署策略），最终发现解决方案是先执行 pulumi refresh --yes 同步状态文件。

我将此问题记录为 BUG-018：

“`

2024-10-20 – BUG-018: Pulumi State Drift During Deploy

Issue: Deploy failed with cryptic “update failed” error after manual GCP console changes

Root Cause: Pulumi state file out of sync with actual infrastructure after teammate made console changes

Solution: Run pulumi refresh --yes before deploy to sync state

Prevention: Add pulumi refresh --yes to CI/CD pipeline before deploys; document that manual console changes require refresh
“`

两天后（10 月 22 日），同一错误再次出现。这次流程如下：
1. 我将错误信息告知 Claude。
2. Claude 自动检查 bugs.md，找到了 BUG-018。
3. Claude 建议执行 pulumi refresh --yes。
4. 问题在 5 分钟内解决。

结果：解决时间从 45 分钟降至 5 分钟，效率提升 89%。

示例 2：保障架构一致性（防止包体积膨胀）

无记忆系统时：
User: "Add a bar chart to the dashboard" Claude: "I'll add Chart.js for the bar chart. Let me install it..." 结果：包体积增加 85KB，引入重复的图表库依赖，样式不统一。

有记忆系统时：
User: "Add a bar chart to the dashboard" Claude: Checking decisions.md... Found: ADR-012 - Use D3.js for all charts (team has D3 expertise, already in bundle) Claude: "I see we've decided to use D3.js for charts. I'll create the bar chart using D3 to match your existing charts." 结果：复用现有 D3.js，样式统一，包体积零增长。

这种一致性会产生“复利”效应。一个关于图表库的决策，可能避免后续数十个潜在的依赖冲突。以上均为真实发生过的场景。

复利效应

告别AI健忘症：构建Claude Code项目记忆系统，每年节省26小时开发时间知识复利时间线：第一次遇到（调试 2 小时）→ 文档化 → 第二次（5 分钟）→ 第三次（2 分钟）→ 预防性建议

知识的记录确实能带来复利回报。上图展示了典型的时间线演进：首次遇到问题（调试 2 小时）→ 记录到文档 → 第二次遇到（5 分钟解决）→ 第三次遇到（2 分钟解决）→ 最终获得预防性建议。

注意其高级形态：到第四次，Claude 的行为从“修复”升级为“预防”。例如：“我注意到您即将进行的操作曾导致过 state drift。是否需要先运行 pulumi refresh？”

你的项目会随着时间推移更易于维护，而不是更难。 这就是知识文档化的复利效应。

跨平台：Agent Skill 标准

project-memory 的强大之处不仅限于 Claude Code。它遵循 Agent Skill Standard (agentskills.io)，这意味着同一个 skill 可以在超过 14 个不同的 AI 编程助手之间通用。该 skill 本身也包含了如何维护 AGENTS.md 文件的说明。

这一点至关重要，因为团队成员往往偏好不同的工具：有人用 Claude Code，有人用 Cursor，还有人依赖 GitHub Copilot。通过标准化的 skills，整个团队可以共享并受益于同一份项目记忆。

告别AI健忘症：构建Claude Code项目记忆系统，每年节省26小时开发时间

上图展示了 Agent Skill Standard 如何让一个 skill 在 Claude Code、Codex、Gemini、Cursor 等工具间通用。

跨平台安装

告别AI健忘症：构建Claude Code项目记忆系统，每年节省26小时开发时间

Agent skills 是跨平台的，因此存在通用的安装器。上图展示了从 GitHub 或 SkillzWave 市场找到 skill，然后使用开源的 skilz CLI 作为安装器，将其分发到 Claude Code、Codex、Gemini、Cursor、GitHub Copilot 等 AI 助手。

使用 skilz CLI 安装 Agent Skill

“`bash

安装 skilz

pip install skilz

为 Claude Code 全局安装

skilz install -g https://github.com/SpillwaveSolutions/project-memory

仅为特定项目安装

skilz install -g https://github.com/SpillwaveSolutions/project-memory –project

为其他 AI 助手安装

skilz install -g https://github.com/SpillwaveSolutions/project-memory –agent codex
skilz install -g https://github.com/SpillwaveSolutions/project-memory –agent gemini
skilz install -g https://github.com/SpillwaveSolutions/project-memory –agent cursor
skilz install -g https://github.com/SpillwaveSolutions/project-memory –agent opencode
“`

同一套项目知识，可以从你使用的任何 AI 编程工具访问。你在 Claude Code 中记录的 Bug 修复，第二天使用 Cursor、Gemini 或 Codex 的同事也能立即受益。

告别AI健忘症：构建Claude Code项目记忆系统，每年节省26小时开发时间

安全：哪些信息绝不能保存

在使用 project-memory 之前，请务必仔细阅读本节内容。

key_facts.md 旨在方便查找项目配置，但便利性往往伴随着风险。切勿在任何 memory 文件中存放密钥或机密信息。 这些 Markdown 文件会被纳入版本控制，任何有仓库访问权限的人都能看到。该 skill 会特别强调这一点。

危险区

以下信息绝不要存放在 key_facts.md（或任何 memory 文件）中：

告别AI健忘症：构建Claude Code项目记忆系统，每年节省26小时开发时间

认证凭据：密码、API 密钥、访问令牌或任何形式的认证机密。
服务账号密钥：GCP/AWS 的 JSON 密钥文件、私钥或服务账号凭据。
OAuth 密钥：客户端密钥、刷新令牌或 OAuth 配置机密。
数据库凭据：包含密码的连接字符串或任何数据库认证信息。
基础设施密钥：SSH 私钥、VPN 凭据或网络访问凭据。

安全区

以下信息可以安全地存放在 key_facts.md 中：

告别AI健忘症：构建Claude Code项目记忆系统，每年节省26小时开发时间

主机名和 URL：例如 api.staging.example.com 或 https://api.example.com/v1。
端口号：例如 PostgreSQL: 5432、Redis: 6379。
项目标识符：例如 GCP 项目 ID、AWS 账户 ID（非敏感部分）。
服务账号邮箱：例如 service-account@project.iam.gserviceaccount.com。
环境名称：例如 staging、production、dev。
公共端点：任何公开可访问的 URL 或 API 端点。
配置值：非敏感设置，如超时时间、重试次数、功能开关。

机密应该存放在哪里

告别AI健忘症：构建Claude Code项目记忆系统，每年节省26小时开发时间

.env 文件（被 .gitignore 忽略）：适合本地开发使用的机密。
云端密钥管理器：生产环境使用 GCP Secret Manager、AWS Secrets Manager、Azure Key Vault。
CI/CD 变量：使用 GitHub Actions secrets、GitLab CI/CD variables 等。
密码管理器：团队共享使用 1Password、LastPass、Bitwarden 等。
环境变量：在部署时注入运行时机密，不要提交到代码库。
Kubernetes Secrets：在容器化场景中使用 Kubernetes Secret 对象。
硬件安全模块：企业级场景下用于保护高度敏感的加密密钥。

💡 建议：立即搜索你现有的 key_facts.md 文件（如果有），查找 password、secret、key、token 等关键词。如果发现任何机密信息，请立即将其迁移到安全位置并轮换这些凭据。

常见陷阱（以及如何避免）

在数十个项目中应用 project-memory 并帮助他人落地后，我们总结出几个高频错误。提前了解并规避它们可以节省大量时间和精力。

陷阱 1：文档荒漠

问题：你满怀热情地搭建了项目记忆系统，写了几条记录后就再也没有更新。六个月后，这些文件已经过时且毫无用处。

坑 2：长篇大论

问题：Bug记录变成了冗长的论文；决策记录写入了完整的讨论历史。内容过长导致无人愿意阅读。

解决：确保每个条目都能在30秒内读完。采用结构化格式（例如：Issue、Root Cause、Solution、Prevention）。如需更多细节，请链接到单独的详细文档。

坑 3：“大杂烩”文件

问题：将所有信息都塞进一个 key_facts.md 文件，最终导致文件长达500行且毫无组织结构。

解决：根据信息类型，分门别类地存入四个独立的文件：
* Bugs → bugs.md
* Decisions → decisions.md
* 配置与关键事实 → key_facts.md
* 工作记录 → issues.md

一个简单的检验标准：如果 key_facts.md 超过100行，很可能混入了“伪装成事实的决策”。

Déjà Vu（似曾相识）陷阱

问题：你再次经历那种熟悉的挫败感——“我肯定见过这个Bug，我记得我们修过，我知道有个变通方案。”但却想不起具体细节，不得不花费半小时重新寻找解决方案。

解决：这正是项目记忆系统旨在消除的场景。当这种“似曾相识”的感觉出现时，你的第一反应应该是：“去查 bugs.md 文件。”那个反复出现的CORS问题？已经记录在案。每周二都会失败的脆弱测试？变通方案已写好。认证的边界情况？早已解决并登记。

其美妙之处在于，项目记忆能够沉淀“部落知识”，使其不再锁在个人脑中。当你的团队决定所有图表都使用D3.js时，这个决定会被记录下来。六个月后，当新成员询问“我们应该用哪个图表库？”时，Claude无需猜测，它会查询 decisions.md 并给出正确答案。

实际效果：不再重复解决同一个问题；不再出现前后不一致的技术选择；不再有“我发誓我们修过这个”的崩溃时刻。重复性工作将停止，因为记忆在持续累积。

坑 4：机密信息仓库

问题：开发者为了“方便”，将API密钥等敏感信息存入 key_facts.md，导致这些密钥永久留存在Git历史中。

解决：请使用 .env 文件管理环境变量，并确保将 .env 添加到 .gitignore 中。如果已经不慎提交过机密信息，请立即进行密钥轮换。仅从Git历史中移除是不够的，因为密钥可能已经被克隆到其他地方。

坑 5：孤岛记忆

问题：只有一位开发者极其认真地维护项目记忆，团队其他成员根本不知道它的存在，从而形成知识孤岛。

解决：在项目的 README 或新成员入职文档中，加入关于项目记忆系统的专门章节。在代码评审（PR Review）中，可以提示：“这个Bug修复应该在 bugs.md 中记录下来。”

坑 6：陈旧的决策

问题：ADR-003 记录着“所有API使用REST”，但团队两年前已经迁移到了GraphQL。记忆文件现在提供了误导性信息。

解决：每季度复查一次决策记录。对于已过时的条目，标记其状态为被替代：**Status**: Superseded by ADR-027。不要删除旧记录，未来的开发者可能会好奇为什么旧代码使用了REST。

构建你自己的Agent Skills

project-memory skill展示了你在构建任何skill时都可以遵循的关键原则。以下指南源于我构建数十个skills的实践经验，并见证了哪些会被长期使用、哪些会被弃用。

1. 解决你真实遇到的问题

当你发现自己处于以下情况时，就是构建skill的好时机：
* 不断向Claude（或队友）重复解释同一件事。
* 反复查找同一条信息。
* 手动重复同一个多步骤流程。
* 希望Claude“本来就知道”某些项目背景。

反模式：不要为假想的问题构建skill。如果你没有亲身体验过那个痛点，就很难设计出正确的解决方案。

2. 保持聚焦（一个Skill = 一个目的）

抵制构建“大一统超级Skill”的冲动。小而专注、可组合的skills更具复用性，也更易于维护。
* 好的例子：project-memory 负责记忆；code-review 负责评审。
* 不好的例子：project-everything 试图管理记忆、评审、部署甚至点咖啡。

3. 使用清晰、自然的触发短语

在skill的描述中，写入用户自然会说出的短语：
* “set up project memory”
* “log this bug”
* “update key facts”
* “track our decisions”

测试时问自己：“我真的会这么说吗？”避免使用行话过重的触发词，例如“initialize documentation subsystem”。

4. 让它看起来像标准文档

放在 docs/ 目录下的文件更可能被维护；放在 ai-stuff/ 这类临时目录下的文件则容易被忽略。
使用团队已有的命名约定来命名文件和目录。如果决策通常放在 adr/ 文件夹，就把相关文件放在那里。如果团队使用Notion，可以考虑创建一个能导出到Notion格式的skill。

5. 包含模板与示例

提供你期望的准确格式。Claude对具体示例的遵循度远高于抽象的说明。

不够有效：
Create a bug entry with relevant information

更有效：
“`

YYYY-MM-DD – Bug Title

Issue: What happened
Root Cause: Why it happened
Solution: How you fixed it
Prevention: How to avoid it
“`

自己试试

准备好将项目记忆融入你的工作流了吗？接下来五分钟就可以开始。

快速起步

“`

安装 skilz CLI

pip install skilz

全局安装 project-memory agent skill（在所有项目中生效）

skilz install https://github.com/SpillwaveSolutions/project-memory
“`

然后在任意项目中打开Claude Code并输入：
"Set up project memory for this project"

Claude将为你创建记忆系统的基础设施，配置你的 CLAUDE.md 文件，一切准备就绪。

如果上述指令无效，你可以尝试：
“`
“Set up project memory for this project using the project memory skill”

或者…

“/project-memory-skill Set up project memory for this project”
“`

该 skill 也能开箱即用地配合 [AGENTS.md](http://AGENTS.md)，因为我经常同时使用 OpenCode 和 Claude Code，我写它时就让它对两者都有效。再强调一下，这是我最早写的 skills 之一，还有很多可改进空间。

你的第一周挑战

不要试图一次性把一切都文档化。相反：

告别AI健忘症：构建Claude Code项目记忆系统，每年节省26小时开发时间

Day 1：搭建项目记忆
Day 2：在 key_facts.md 中添加一个你老是忘的 URL 或端口
Day 3：当你修了一个 bug，就在 bugs.md 里记录
Day 4：在 decisions.md 里记录一项架构决策
Day 5：问 Claude 一个你之前记录过的问题

到第 5 天，你会体验第一次“啊哈”时刻：Claude 记得你几天前告诉它的事情。价值从这时开始变得真实。

成功的样子

一周后，你应该已经：

在 memory 文件里写了 3–5 条目
至少经历过一次 Claude 利用记忆帮助你的情况
开始形成记录习惯

一个月后：

memory 文件里有 15–25 条目
多次通过 memory 查找节省时间
队友开始问：“Claude 是怎么知道这个的？”

未来改进：让 Project Memory 更强

虽然这个 skill 解决了 AI 健忘症的核心问题，但仍有不少可提升空间。以下改进能把 project memory 提升到新层级：

1. 自动生成目录（TOC）

需求：当 bugs.md、decisions.md、key_facts.md 超过 50–100 条目时，查找会变难。AI coding assistants 会用 agentic search，但结构化导航对人和 AI 都有帮助。

方案：超过阈值（如 20 条目）时，在文件顶部自动生成目录。这能提升语义搜索效果，也能大幅加快人工浏览。这也有助于“部分发现”（partial discovery）架构。

“`

Authentication Issues
Database Performance
CORS Problems
“`

2. 自动归档老文件

需求：两年前的 bug 不如近期的相关。把所有内容塞在一个文件会制造噪音、降低搜索质量。这是对 TOC 的补充。

方案：对 bugs.md 和 issues.md 实现自动归档：

把 6–12 个月前的 bug 移到 bugs-archive-2025.md
在主文件中保留引用：See bugs-archive-2025.md for older entries
decisions 和 key facts 通常无需归档。它们的时效性较弱，除非决策改变。

3. Multi-Agent 支持（超越 Claude）

需求：skill 最初创建时，Claude Code skills 还不是开放标准。现在有了 Agent Skill Standard，我们可以让 project memory 真正通用。

方案：让 skill 能检测并配置多个 AI coding assistants：

如果使用 Claude Code，更新 CLAUDE.md
如果使用 Gemini，更新 GEMINI.md
如果使用 Codex 或其他工具，更新 AGENT.md 或询问配置文件位置

skill 可在设置时询问：“你使用哪些 AI coding assistant？”并自动配置相关文件。

演进仍在继续：这些未来改进反映了我们对 AI coding assistants 与 agentic search 能力的更深入理解。随着生态成熟、我们对 agent 如何使用项目记忆的认知加深，skill 也会持续演进。

好处是：这些增强可以逐步添加，而不会破坏现有功能。从基础开始，再按需叠加复杂性。

结语：从小处开始，快速复利

project-memory 故意保持简单。它就是一个包含 SKILL.md 和一些模板文件的文件夹，总计可能不到 300 行。但这点投入，为我节省了数十小时，因为它能：

消灭重复调试（同一个 bug 不会第二次再花 45 分钟）
保持架构一致性（不再无意间引入多余框架）
在会话间保留项目知识（上下文不再随对话重启而消失）
跨多个 AI 编码工具工作（团队共同受益）

更重要的是，它证明了小而专注的 skills 也能产生巨大影响。你并不需要复杂自动化。有时，一份结构化的 markdown 与明确的协议就足够了。

我的建议：今天就安装 project-memory。本周记录一个 bug、一个决定和一个关键事实。亲身体验“记忆的复利”。

然后，当你第三次向 Claude 解释同一件事情时，写一个你自己的 skill。从小做起，解决真实问题，看时间节省如何不断复利。

未来的你——那个不用第五次再去解决 CORS 问题的你——会感谢现在的决定。

Notion Uploader/Downloader Agent Skill：在文档工作流中，将 Markdown 内容与图片无缝上传/下载至 Notion。
Confluence Agent Skill：将 Markdown 内容与图片上传/下载到 Confluence，适用于企业文档管理。
JIRA Integration Agent Skill：创建与读取 JIRA 工单，支持处理特殊必填字段。

我开发了一个桌面应用 Agent Skill Viewer，用于评估 Agent Skills 的安全性、实用性、链接与 PDA。

告别AI健忘症：构建Claude Code项目记忆系统，每年节省26小时开发时间

Advanced Development Agents

Architect Agent Skill：让 Claude Code 进入架构师模式，管理多个项目，并将任务委派给其他运行专门代码任务的 Claude Code 实例。
Project Memory Agent Skill：存储关键决策、反复出现的错误、工单以及关键事实，在开发过程中持续保有项目上下文。

Visualization & Design Tools

Design Doc Mermaid Agent Skill：专为创建专业的 Mermaid 架构图而设计。
PlantUML Agent Skill：从源码生成 PlantUML 图，从 Markdown 中提取图表，并创建可链接图片的文档。
Image Generation Agent Skill：使用 Gemini Banana 生成用于文档与设计的图片。
SDD Agent Skill：围绕 GitHub 的 Spec-Kit 和 Spec-Driven Development 方法论的完整 Claude Code Skill。
PR Reviewer Agent Skill：面向 GitHub PR 的全面代码审查 Skill。通过 gh CLI 自动收集数据，按业界标准（安全、测试、可维护性）进行分析，生成结构化评审文件，并发布带批准流程的反馈。包括行内评论、工单追踪与专业评审模板。

AI Model Integration

Gemini Agent Skill：将特定任务委派给 Google 的 Gemini AI，实现多模型协作。
Image_gen Agent Skill：使用 Gemini Banana 进行图像生成。

Full Skill Markdown file

name: project-memory
description: Set up and maintain a structured project memory system in docs/project_notes/ that tracks bugs with solutions, architectural decisions, key project facts, and work history. Use this skill when asked to “set up project memory”, “track our decisions”, “log a bug fix”, “update project memory”, or “initialize memory system”. Configures both CLAUDE.md and AGENTS.md to maintain memory awareness across different AI coding tools.

Project Memory

Overview
When to Use This Skill
Core Capabilities
1. Initial Setup – Create Memory Infrastructure
2. Configure CLAUDE.md – Memory-Aware Behavior
3. Configure AGENTS.md – Multi-Tool Support
4. Searching Memory Files
5. Updating Memory Files
6. Memory File Maintenance
Templates and References
Example Workflows
Integration with Other Skills
Success Criteria

Overview

Maintain institutional knowledge for projects by establishing a structured memory system in docs/project_notes/. This skill sets up four key memory files (bugs, decisions, key facts, issues) and configures CLAUDE.md and AGENTS.md to automatically reference and maintain them. The result is a project that remembers past decisions, solutions to problems, and important configuration details across coding sessions and across different AI tools.

When to Use This Skill

Invoke this skill when:

Starting a new project that will accumulate knowledge over time
The project already has recurring bugs or decisions that should be documented
The user asks to “set up project memory” or “track our decisions”
The user wants to log a bug fix, architectural decision, or completed work
Encountering a problem that feels familiar (“didn’t we solve this before?”)
Before proposing an architectural change (check existing decisions first)
Working on projects with multiple developers or AI tools (Claude Code, Cursor, etc.)

Core Capabilities

1. Initial Setup – Create Memory Infrastructure

When invoked for the first time in a project, create the following structure:

“`
docs/
└── project_notes/
├── bugs.md # Bug log with solutions
├── decisions.md # Architectural Decision Records
├── key_facts.md # Project configuration and constants
└── issues.md # Work log with ticket references

Directory naming rationale: Using docs/project_notes/ instead of memory/ makes it appear as standard engineering organization, not AI-specific tooling. This increases adoption and maintenance by human developers.

Initial file content: Copy templates from the references/ directory in this skill:
– Use references/bugs_template.md for initial bugs.md
– Use references/decisions_template.md for initial decisions.md
– Use references/key_facts_template.md for initial key_facts.md
– Use references/issues_template.md for initial issues.md

Each template includes format examples and usage tips.

2. Configure CLAUDE.md – Memory-Aware Behavior

Add or update the following section in the project’s CLAUDE.md file:

“`markdown

Project Memory System

This project maintains institutional knowledge in docs/project_notes/ for consistency across sessions.

Memory Files

bugs.md – Bug log with dates, solutions, and prevention notes
decisions.md – Architectural Decision Records (ADRs) with context and trade-offs
key_facts.md – Project configuration, credentials, ports, important URLs
issues.md – Work log with ticket IDs, descriptions, and URLs

Memory-Aware Protocols

Before proposing architectural changes:
– Check docs/project_notes/decisions.md for existing decisions
– Verify the proposed approach doesn’t conflict with past choices
– If it does conflict, acknowledge the existing decision and explain why a change is warranted

When encountering errors or bugs:
– Search docs/project_notes/bugs.md for similar issues
– Apply known solutions if found
– Document new bugs and solutions when resolved

When looking up project configuration:
– Check docs/project_notes/key_facts.md for credentials, ports, URLs, service accounts
– Prefer documented facts over assumptions

When completing work on tickets:
– Log completed work in docs/project_notes/issues.md
– Include ticket ID, date, brief description, and URL

When user requests memory updates:
– Update the appropriate memory file (bugs, decisions, key_facts, or issues)
– Follow the established format and style (bullet lists, dates, concise entries)

Style Guidelines for Memory Files

Prefer bullet lists over tables for simplicity and ease of editing
Keep entries concise (1-3 lines for descriptions)
Always include dates for temporal context
Include URLs for tickets, documentation, monitoring dashboards
Manual cleanup of old entries is expected (not automated)
“`

3. Configure AGENTS.md – Multi-Tool Support

If the project has an AGENTS.md file (used for agent workflows or multi-tool projects), add the same memory protocols. This ensures consistency whether using Claude Code, Cursor, GitHub Copilot, or other AI tools.

If AGENTS.md exists: Add the same “Project Memory System” section as above.
“`

4. 搜索记忆文件

在遇到问题或需要做决策时，主动搜索记忆文件：

搜索 bugs.md:
“`bash

查找类似错误

grep -i “connection refused” docs/project_notes/bugs.md

按日期范围查找错误

grep “2025-01” docs/project_notes/bugs.md
“`

搜索 decisions.md:
“`bash

检查关于某项技术的决策

grep -i “database” docs/project_notes/decisions.md

查找所有 ADR

grep “^### ADR-” docs/project_notes/decisions.md
“`

搜索 key_facts.md:
“`bash

查找数据库连接信息

grep -A 5 “Database” docs/project_notes/key_facts.md

查找服务账户信息

grep -i “service account” docs/project_notes/key_facts.md
“`

使用 Grep 工具进行更复杂的搜索：
* 跨所有记忆文件搜索：Grep(pattern="oauth", path="docs/project_notes/")
* 上下文感知搜索：Grep(pattern="bug", path="docs/project_notes/bugs.md", -A=3, -B=3)

5. 更新记忆文件

当用户请求更新或记录已解决的问题时，更新相应的记忆文件：

添加错误记录：
“`

YYYY-MM-DD – 简要错误描述

问题：发生了什么错误
根本原因：为什么会发生
解决方案：如何修复的
预防措施：未来如何避免
“`

添加决策记录：
“`

ADR-XXX: 决策标题 (YYYY-MM-DD)

背景：
– 为什么需要此决策
– 它解决了什么问题

决策：
– 选择了什么方案

考虑的替代方案：
– 方案 1 -> 被拒绝的原因
– 方案 2 -> 被拒绝的原因

后果：
– 好处
– 权衡取舍
“`

添加关键事实：
* 按类别组织（GCP 项目、数据库、API、本地开发等）
* 使用项目符号列表以提高清晰度
* 包含生产和开发环境的详细信息
* 添加 URL 以便快速导航
* 有关不应存储哪些内容的安全指南，请参阅 references/key_facts_template.md

添加工作日志条目：
“`

YYYY-MM-DD – TICKET-ID: 简要描述

状态：已完成 / 进行中 / 已阻塞
描述：1-2 行摘要
URL：https://jira.company.com/browse/TICKET-ID
备注：任何重要的上下文信息
“`

6. 记忆文件维护

定期清理旧条目：
* 用户负责手动清理（无自动化）
* 删除不再相关的非常旧的错误条目（6 个月以上）
* 归档已完成的工作条目（3 个月以上）
* 保留所有决策记录（它们很轻量且提供历史背景）
* 项目配置更改时更新 key_facts.md

冲突解决：
* 如果提议的内容与 decisions.md 中的决策冲突，请解释为何需要重新审视该决策
* 如果选择发生变化，则更新决策条目
* 添加修订日期以显示演变过程

模板和参考

此技能在 references/ 目录中包含模板文件，用于演示正确的格式：

references/bugs_template.md – Bug 记录模板及示例
references/decisions_template.md – 架构决策记录模板及示例
references/key_facts_template.md – 关键事实组织模板及示例（包含安全指南）
references/issues_template.md – 工作日志模板及示例

创建初始记忆文件时，请将这些模板复制到 docs/project_notes/ 目录下，并根据项目进行定制。

示例工作流

场景一：遇到已知 Bug

用户：“数据库报‘connection refused’错误” -> 在 docs/project_notes/bugs.md 中搜索“connection” -> 找到历史解决方案：“在端口 5432 上使用 AlloyDB Auth Proxy” -> 应用已知修复

场景二：提议架构变更

内部讨论：“用户可能受益于使用 SQLAlchemy 进行迁移” -> 查阅 docs/project_notes/decisions.md -> 找到 ADR-002：已决定使用 Alembic -> 转而使用 Alembic，保持一致性

场景三：用户请求更新记忆

用户：“把那个 CORS 修复方案加到 bug 日志里” -> 阅读 docs/project_notes/bugs.md -> 添加新条目（日期、问题、解决方案、预防措施） -> 向用户确认已添加

场景四：查找项目配置

内部需求：“需要连接数据库” -> 查阅 docs/project_notes/key_facts.md -> 找到“数据库配置”部分 -> 使用文档化的连接字符串和凭据

高效记忆管理技巧

主动查阅：在提出解决方案前，先检查记忆文件。
保持简洁：条目描述应简短（1-3 行）。
标注日期：始终包含日期以提供时间上下文。
建立链接：包含指向工单、文档、监控面板的 URL。
有所选择：关注重复性或具有指导意义的问题，而非每个 Bug。

与其他技能的集成

项目记忆技能与其他技能形成互补：

需求文档化：需求 -> 决策（ADR 引用需求）
根因调试：Bug 诊断 -> Bug 日志（修复后记录解决方案）
代码质量审查：质量问题 -> 决策（记录质量标准）
文档同步编辑：代码变更 -> 关键事实（配置变更时更新）

当组合使用这些技能时，应考虑将更新记忆文件作为后续操作。

成功标准

当满足以下条件时，表明此技能已成功部署：

docs/project_notes/ 目录存在，并包含全部四个记忆文件。
CLAUDE.md 文件中包含“项目记忆系统”章节及协议。
AGENTS.md 文件包含相同协议（如果文件存在或用戶要求）。
记忆文件遵循模板格式和风格指南。
AI 助手在提出变更建议前会检查记忆文件。
用户可以轻松请求记忆更新（例如“将此添加到 bugs.md”）。
记忆文件看起来像标准的工程文档，而非 AI 产物。

关注“鲸栖”小程序，掌握最新AI资讯

本文来自网络搜集，不代表鲸林向海立场，如有侵权，联系删除。转载请注明出处：https://www.itsolotime.com/archives/20421

告别AI健忘症：构建Claude Code项目记忆系统，每年节省26小时开发时间

一个不到 300 行的 skill，如何变成我最常用的 AI 辅助开发效率工具

AI 健忘症的真实成本

什么是 Claude Code Agent Skill？

Agent Skill 结构剖析

Skill 激活如何运作

Project Memory Agent Skill

Memory 文件结构

第 1 部分：Agent Skill 的 Frontmatter（它的“何时”）

“`yaml

第 2 部分：何时使用该 Agent Skill（上下文触发）

When to Use This Skill

第 3 部分：初始设置指令（它的“做什么”）

Core Capabilities

1. Initial Setup – Create Memory Infrastructure

第 4 部分：Memory 条目格式（结构化知识）

第 5 部分：CLAUDE.md 的记忆协议（核心机制）

2. Configure CLAUDE.md – Memory-Aware Behavior

Project Memory System

Memory-Aware Protocols

实战影响：知识的复利效应

记忆驱动的 Bug 处理

示例 1：修复速度提升（真实数据）

2024-10-20 – BUG-018: Pulumi State Drift During Deploy

示例 2：保障架构一致性（防止包体积膨胀）

复利效应

跨平台：Agent Skill 标准

跨平台安装

使用 skilz CLI 安装 Agent Skill

安装 skilz

为 Claude Code 全局安装

仅为特定项目安装

为其他 AI 助手安装

安全：哪些信息绝不能保存

危险区

安全区

机密应该存放在哪里

常见陷阱（以及如何避免）

陷阱 1：文档荒漠

坑 2：长篇大论

坑 3：“大杂烩”文件

Déjà Vu（似曾相识）陷阱

坑 4：机密信息仓库

坑 5：孤岛记忆

坑 6：陈旧的决策

构建你自己的Agent Skills

1. 解决你真实遇到的问题

2. 保持聚焦（一个Skill = 一个目的）

3. 使用清晰、自然的触发短语

4. 让它看起来像标准文档

5. 包含模板与示例

YYYY-MM-DD – Bug Title

自己试试

快速起步

安装 skilz CLI

全局安装 project-memory agent skill（在所有项目中生效）

你的第一周挑战

成功的样子

未来改进：让 Project Memory 更强

1. 自动生成目录（TOC）

Table of Contents

2. 自动归档老文件

3. Multi-Agent 支持（超越 Claude）

结语：从小处开始，快速复利

Advanced Development Agents

Visualization & Design Tools

AI Model Integration

Full Skill Markdown file

Project Memory

Table of Contents

Overview

When to Use This Skill

Core Capabilities

1. Initial Setup – Create Memory Infrastructure

2. Configure CLAUDE.md – Memory-Aware Behavior

Project Memory System

Memory Files

Memory-Aware Protocols

Style Guidelines for Memory Files

3. Configure AGENTS.md – Multi-Tool Support