project-memory

项目记忆

目录

• 概述
• 何时使用此技能
• 核心功能
  • 1. 初始设置 - 创建记忆基础设施
  • 2. 配置 CLAUDE.md - 支持记忆的行为
  • 3. 配置 AGENTS.md - 支持多种工具
  • 4. 搜索记忆文件
  • 5. 更新记忆文件
  • 6. 维护记忆文件
• 模板和参考资料
• 示例工作流
• 与其他技能集成
• 成功标准

概述

通过在 docs/project_notes/ 中建立结构化的记忆系统，维护项目的机构知识。此技能会设置四个关键记忆文件（错误、决策、关键信息、问题），并配置 CLAUDE.md 和 AGENTS.md，使其自动引用和维护这些文件。这样，项目就能在不同的编码会话和不同的 AI 工具中记住以往的决策、问题的解决方案以及重要的配置细节。

何时使用此技能

在以下情况下调用此技能：

• 开始一个会随时间积累知识的新项目
• 项目中已有需要记录的反复出现的错误或决策
• 用户要求“设置项目记忆”或“跟踪我们的决策”
• 用户想要记录错误修复、架构决策或已完成的工作
• 遇到似曾相识的问题（“我们以前不是解决过这个问题吗？”）
• 提出架构变更之前（先检查现有决策）
• 参与有多位开发者或多种 AI 工具（Claude Code、Cursor 等）的项目

核心功能

1. 初始设置 - 创建记忆基础设施

首次在项目中调用时，创建以下结构：

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

目录命名理由： 使用 docs/project_notes/ 而不是 memory/，看起来更像标准的工程组织方式，而非 AI 专用工具。这有助于提高开发者的采用率和维护意愿。

初始文件内容： 从此技能的 references/ 目录中复制模板：

• 使用 references/bugs_template.md 作为初始的 bugs.md
• 使用 references/decisions_template.md 作为初始的 decisions.md
• 使用 references/key_facts_template.md 作为初始的 key_facts.md
• 使用 references/issues_template.md 作为初始的 issues.md

每个模板都包含格式示例和使用提示。

2. 配置 CLAUDE.md - 支持记忆的行为

在项目的 CLAUDE.md 文件中添加或更新以下部分：

## 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. 配置 AGENTS.md - 支持多种工具

如果项目有 AGENTS.md 文件（用于 Agent 工作流或多工具项目），请添加相同的记忆协议。这样，无论使用 Claude Code、Cursor、GitHub Copilot 还是其他 AI 工具，都能保持一致。

如果 AGENTS.md 存在： 添加与上述相同的“项目记忆系统”部分。

如果 AGENTS.md 不存在： 询问用户是否要创建该文件。许多项目会使用多种 AI 工具，并会受益于共享的记忆协议。

4. 搜索记忆文件

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

搜索 bugs.md：

# Look for similar errors
grep -i "connection refused" docs/project_notes/bugs.md

# Find bugs by date range
grep "2025-01" docs/project_notes/bugs.md

搜索 decisions.md：

# Check for decisions about a technology
grep -i "database" docs/project_notes/decisions.md

# Find all ADRs
grep "^### ADR-" docs/project_notes/decisions.md

搜索 key_facts.md：

# Find database connection info
grep -A 5 "Database" docs/project_notes/key_facts.md

# Look up service accounts
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 - Brief Bug Description
- **Issue**: What went wrong
- **Root Cause**: Why it happened
- **Solution**: How it was fixed
- **Prevention**: How to avoid it in the future

添加决策：

### ADR-XXX: Decision Title (YYYY-MM-DD)

**Context:**
- Why the decision was needed
- What problem it solves

**Decision:**
- What was chosen

**Alternatives Considered:**
- Option 1 -> Why rejected
- Option 2 -> Why rejected

**Consequences:**
- Benefits
- Trade-offs

添加关键信息：

• 按类别整理（GCP 项目、数据库、API、本地开发等）
• 使用项目符号列表，便于阅读
• 同时包含生产环境和开发环境的详细信息
• 添加 URL，便于快速导航
• 有关不应存储哪些内容的安全指南，请参阅 references/key_facts_template.md

添加工作日志条目：

### YYYY-MM-DD - TICKET-ID: Brief Description
- **Status**: Completed / In Progress / Blocked
- **Description**: 1-2 line summary
- **URL**: https://jira.company.com/browse/TICKET-ID
- **Notes**: Any important context

6. 维护记忆文件

定期清理旧条目：

• 用户负责手动清理（不使用自动化）
• 删除不再相关的过旧错误条目（6 个月以上）
• 将 issues.md 中已完成的工作归档（3 个月以上）
• 保留所有决策（它们简明扼要，能提供历史背景）
• 项目配置发生变化时，更新 key_facts.md

冲突解决：

• 如果提议的内容与 decisions.md 中的决策冲突，请说明重新审视该决策的理由
• 如果选择发生变化，请更新决策条目
• 添加修订日期，以体现变化过程

模板和参考资料

此技能在 references/ 中包含展示正确格式的模板文件：

• references/bugs_template.md - 错误条目格式及示例
• references/decisions_template.md - ADR 格式及示例
• references/key_facts_template.md - 关键信息的组织方式及示例（包含安全指南）
• references/issues_template.md - 工作日志格式及示例

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

工作流示例

场景 1：遇到熟悉的错误

User: "I'm getting a 'connection refused' error from the database"
-> Search docs/project_notes/bugs.md for "connection"
-> Find previous solution: "Use AlloyDB Auth Proxy on port 5432"
-> Apply known fix

场景 2：提出架构变更

Internal: "User might benefit from using SQLAlchemy for migrations"
-> Check docs/project_notes/decisions.md
-> Find ADR-002: Already decided to use Alembic
-> Use Alembic instead, maintaining consistency

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

User: "Add that CORS fix to our bug log"
-> Read docs/project_notes/bugs.md
-> Add new entry with date, issue, solution, prevention
-> Confirm addition to user

场景 4：查询项目配置

Internal: "Need to connect to database"
-> Check docs/project_notes/key_facts.md
-> Find Database Configuration section
-> Use documented connection string and credentials

有效管理记忆的技巧

1. 主动检查：提出解决方案前，先检查记忆文件
2. 简明扼要：条目应简短（描述控制在 1–3 行）
3. 注明日期：始终包含日期，以提供时间背景
4. 添加链接：包含指向工单、文档和监控仪表板的 URL
5. 有所取舍：关注反复出现或具有指导意义的问题，而不是记录每个错误

与其他技能集成

project-memory 技能可与其他技能互补：

• requirements-documenter：需求 -> 决策（ADR 引用需求）
• root-cause-debugger：错误诊断 -> 错误日志（修复后记录解决方案）
• code-quality-reviewer：质量问题 -> 决策（记录质量标准）
• docs-sync-editor：代码变更 -> 关键信息（配置变更时更新）

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

成功标准

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

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