Skip to content

RRFRRF/project-memory-skill / project-memory-cn

project-memory-cn

Verified

初始化轻量级项目记忆系统。创建 CLAUDE.md、AGENTS.md、LOOP.md、BUGS.md 与 .mem/ 文件。初始化后日常维护规则已嵌入 AGENTS.md(通过系统提示词持续生效),无需重复调用本 skill。仅用于初始化、记忆状态查询、压缩清理。默认中文。

project-memory-cn

你负责维护一个轻量级项目记忆系统。它用于跨 agent、跨 session 的代码项目协作。

目标是让新 session 快速知道:

  • 项目是什么
  • 当前做到哪里
  • 有哪些 bug 优先处理
  • 做过哪些长期决策
  • 上一个 session 留下了什么交接
  • 下一步应继续哪里

核心原则:

读得快,写得少,只记录会影响下一次 agent 判断的内容。

默认使用中文回复和维护记忆文件,除非用户或项目要求英文。


1. 目标结构

在仓库根目录维护:

project-root/
├── CLAUDE.md
├── AGENTS.md
├── LOOP.md
├── BUGS.md
└── .mem/
    ├── project.md
    ├── state.md
    ├── decisions.md
    └── handoff.md

职责:

  • CLAUDE.md:Claude Code 入口,只导入 AGENTS.md
  • AGENTS.md:共享项目规则入口
  • BUGS.md:轻量 bug 队列
  • LOOP.md:长期目标和循环约束
  • .mem/project.md:稳定项目事实
  • .mem/state.md:当前进度和下一步
  • .mem/decisions.md:长期 ADR 决策
  • .mem/handoff.md:跨 session 交接记录

2. 激活场景

本 skill 的核心职责是初始化记忆系统。初始化完成后,AGENTS.md 中已包含完整的工作规则、更新原则、协作规则和安全规则——这些规则通过 CLAUDE.md → @AGENTS.md 作为系统提示词持续生效。日常更新 .mem/state.md、BUGS.md、.mem/handoff.md 等操作由 AGENTS.md 驱动,无需重复调用本 skill。

仅在以下场景调用本 skill:

  • 初始化项目记忆 / 建立记忆系统
  • 查看记忆状态(用户明确询问"记忆状态")
  • 压缩/清理记忆文件
  • 用户明确要求使用 project-memory skill

注意:如果项目缺少记忆文件,但用户没有明确要求初始化,不要擅自创建整套记忆系统。可以简短提醒用户此项目适合初始化项目记忆。


3. 初始化协议

只有当用户明确要求初始化项目记忆时,才创建完整记忆系统。

用户要求初始化时:

  1. 识别仓库根目录。
  2. 生成本 session 代号。
  3. 创建缺失文件:
    • CLAUDE.md
    • AGENTS.md
    • LOOP.md
    • BUGS.md
    • .mem/project.md
    • .mem/state.md
    • .mem/decisions.md
    • .mem/handoff.md
  4. CLAUDE.md 写入一行:@AGENTS.md
  5. 扫描仓库中可验证的信息,例如:
    • README.md
    • package.json
    • pyproject.toml
    • requirements.txt
    • pnpm-lock.yaml
    • docker-compose.yml
    • Dockerfile
    • Makefile
    • src/
    • tests/
  6. 能确认的项目事实写入 .mem/project.md。
  7. 不能确认的不要编造;少写 未知,统一放到 To Verify。
  8. 在 .mem/handoff.md 登记当前 session。
  9. 在 .mem/decisions.md 添加 ADR-001,说明采用该项目记忆系统。
  10. 不要保存密钥、token、密码或 .env 内容。

4. 会话代号

每个 session 启动时创建唯一代号:

<agent>-YYYYMMDD-HHMM-<short-id>

示例:

claude-20260504-0930-a1b2
codex-20260504-0942-b8c1
agent-20260504-1010-k7d3

如果代理身份未知,用 agent。


5. 读取协议

非平凡工作开始前读取:

  1. AGENTS.md
  2. BUGS.md
  3. .mem/project.md
  4. .mem/state.md
  5. .mem/decisions.md
  6. .mem/handoff.md
  7. 如涉及长期目标,再读取 LOOP.md

不要把全部记忆内容复述给用户,除非用户明确要求。


6. 更新原则

默认只更新最相关的文件,不要每次都同时改所有记忆文件。

更新触发条件:

  • .mem/state.md:有实质进展、阻塞或下一步变化
  • .mem/handoff.md:暂停、结束、切换上下文或交接
  • BUGS.md:发现、修复、验证或延后 bug
  • .mem/decisions.md:做出长期架构/工具/接口决策
  • .mem/project.md:稳定事实变化
  • LOOP.md:用户给出长期目标、循环目标或持续约束

7. 协作规则

.mem/handoff.md 是弱协作信号,不是严格锁。

如果看到其他近期 active session:

  • 避免修改同一批文件
  • 必须重叠时,在 .mem/handoff.md 的 Messages 里留下说明
  • 不要因为看到 active session 就停止工作,除非确实存在冲突

如果某个 session 的 Last Seen 超过 2 小时,除非备注明确说明仍在工作,否则默认视为 stale,不阻塞当前工作。

如果只有自己工作:

  • 可以直接更新 .mem/state.md 的全局状态

8. BUG 规则

BUGS.md 是轻量队列,不是完整 issue 系统。

优先级:

  • P0:阻塞构建、启动、测试、数据完整性或关键流程
  • P1:严重功能缺陷
  • P2:重要但不阻塞
  • P3:小问题、优化、清理

状态:

  • open
  • doing
  • fixed
  • verified
  • deferred
  • wontfix

规则:

  • 开始有意义任务前检查相关 P0/P1 bug。
  • 只优先处理与当前任务相关的 P0/P1 bug。
  • 无关 bug 只记录或提醒,不打断当前任务。
  • 修复 bug 后写明验证方式。
  • 不要静默删除 bug;可以移动到 Fixed。

9. ADR 规则

.mem/decisions.md 只记录长期决策。

应该写 ADR 的例子:

  • 选择某个框架
  • 更换数据库
  • 确定 browser automation 方案
  • 确定 agent 架构
  • 确定关键接口或数据模型
  • 确定测试策略

不应该写 ADR 的例子:

  • 修一个 bug
  • 改变量名
  • 增加一个小工具函数
  • 临时调试结论
  • 单次任务计划

10. LOOP 规则

LOOP.md 默认可以是 inactive。

只有当用户要求:

  • 持续迭代
  • 一直做直到完成
  • 使用 goal/loop 模式
  • 给长期目标或持续约束

才更新 LOOP.md。

LOOP.md 不应覆盖最新用户指令。最新用户指令优先。


11. 安全规则

记忆文件是明文,可能进入 git。

不要保存:

  • API key
  • 密码
  • token
  • 私钥
  • session cookie
  • .env 内容
  • 生产密钥
  • OAuth secret
  • 敏感个人信息

如果用户要求保存这些内容,说明风险并拒绝写入记忆文件。


12. 冲突处理

如果记忆与代码冲突:

  1. 以实际代码为准。
  2. 说明记忆可能过时。
  3. 在合适时更新记忆。

如果记忆与最新用户指令冲突:

  1. 以最新用户指令为准。
  2. 如果是长期变化,更新记忆。

文件优先级:

  1. 最新用户指令
  2. 实际代码和测试结果
  3. AGENTS.md
  4. LOOP.md
  5. BUGS.md
  6. .mem/decisions.md
  7. .mem/state.md
  8. .mem/handoff.md
  9. .mem/project.md

13. 模板

13.1 CLAUDE.md

@AGENTS.md

13.2 AGENTS.md

# AGENTS.md

## 角色

你是一个 AI 编码代理,负责在本仓库中进行小而正确、可验证的代码修改。

默认使用中文回复用户并维护项目记忆,除非用户或项目另有要求。

## 项目记忆系统

本仓库使用轻量项目记忆系统:

```text
project-root/
├── CLAUDE.md
├── AGENTS.md
├── LOOP.md
├── BUGS.md
└── .mem/
    ├── project.md
    ├── state.md
    ├── decisions.md
    └── handoff.md

必读

非平凡修改前读取:

  1. AGENTS.md
  2. BUGS.md
  3. .mem/project.md
  4. .mem/state.md
  5. .mem/decisions.md
  6. .mem/handoff.md
  7. 如涉及长期目标,再读取 LOOP.md

工作规则

  • 开始有意义任务前,检查 BUGS.md 中相关 P0/P1 缺陷。
  • 只优先处理与当前任务相关的 P0/P1 bug;无关 bug 不打断当前任务。
  • 取得实质进展、遇到阻塞或改变下一步时,更新 .mem/state.md。
  • 暂停、结束、切换上下文或需要交接时,更新 .mem/handoff.md。
  • 发现、修复、验证或延后 bug 时,更新 BUGS.md。
  • 只有长期架构/工具/接口决策才写入 .mem/decisions.md。
  • 只有稳定项目事实变化才更新 .mem/project.md。
  • 只有用户给长期目标或循环约束时才更新 LOOP.md。
  • 默认只更新最相关的记忆文件,不要为了形式同时修改全部文件。

协作规则

  • 每个 session 创建唯一代号:<agent>-YYYYMMDD-HHMM-<short-id>。
  • .mem/handoff.md 是弱协作信号,不是严格锁。
  • 如果看到其他近期活跃 session,避免修改同一批文件。
  • 如果某个 session 的 Last Seen 超过 2 小时,除非备注明确说明仍在工作,否则默认视为 stale。
  • 如必须重叠修改,请在 .mem/handoff.md 留下协调说明。

开发规则

  • 修改前先阅读相关源码。
  • 优先做小而聚焦的改动。
  • 不要无故大规模重写。
  • 不要删除用户未明确要求删除的内容。
  • 尽量运行最小有效验证。
  • 无法验证时,说明原因和风险。

安全规则

不要在记忆文件中保存 API key、密码、token、私钥、.env 内容、生产密钥或敏感个人信息。

完成汇报

完成有意义工作后,简要说明:

  1. 改了什么
  2. 如何验证
  3. 更新了哪些记忆文件
  4. 下一步是什么

---

### 13.3 LOOP.md

```markdown
# LOOP

## Status

No active loop goal.

## Objective

-

## Done Criteria

- [ ]

## Constraints

-

## Procedure

1. Read `AGENTS.md`, `BUGS.md`, and `.mem/`.
2. Check current objective and constraints.
3. Pick the highest-impact next task.
4. Handle relevant P0/P1 bugs first.
5. Make one small verifiable change.
6. Run the smallest useful verification.
7. Update the relevant memory file.
8. Stop when done criteria or stop conditions are met.

## Stop Conditions

- Done criteria are complete.
- The next step requires user input.
- Verification fails and the cause is unclear.
- Continuing would require risky or broad architectural changes.
- Another active session is working on the same files and coordination is needed.

## Last Updated

-

13.4 BUGS.md

# BUGS

轻量缺陷队列。开始有意义任务前检查相关 P0/P1 bug。

Priority: P0 blocking, P1 serious, P2 important, P3 minor.  
Status: open, doing, fixed, verified, deferred, wontfix.

## Open

### BUG-YYYYMMDD-001 — Title

- Priority: P1
- Status: open
- Owner: unassigned
- Area:
- Symptom:
- Repro:
- Notes:

## Fixed

### BUG-YYYYMMDD-000 — Title

- Fixed by:
- Verification:
- Notes:

13.5 .mem/project.md

# Project Memory

稳定项目事实。只记录已验证、会影响后续开发判断的信息。

## Summary

-

## Verified Facts

-

## Tech Stack

-

## Architecture

-

## Commands

- Install:
- Dev:
- Test:
- Build:
- Lint:
- Typecheck:

## Known Pitfalls

-

## To Verify

-

## Last Updated

-

13.6 .mem/state.md

# Current State

## Goal

-

## Now

-

## Progress

- [ ]

## Blockers

- None

## Next

1.

## Workstreams

- default: unassigned / idle / -

## Last Updated

-

13.7 .mem/decisions.md

# Decisions

只记录会影响未来开发路径的长期决策。

## ADR Index

- ADR-001 — YYYY-MM-DD — Use lightweight project memory — accepted

## ADR-001 — Use lightweight project memory

- Date: YYYY-MM-DD
- Status: accepted
- Owner: session-id
- Context: 项目需要跨 agent、跨 session 共享状态、缺陷、决策和交接信息。
- Decision: 使用 `CLAUDE.md`、`AGENTS.md`、`LOOP.md`、`BUGS.md` 和 `.mem/` 组成轻量项目记忆系统。
- Alternatives:
  - 全局个人记忆
  - 数据库存储
  - 不保存项目记忆
- Consequences:
  - agent 能更容易接力和协作
  - 需要保持记忆精简并避免保存敏感信息

13.8 .mem/handoff.md

# Handoff

跨 session 交接记录。它是弱协作信号,不是严格锁。

如果某个 session 的 `Last Seen` 超过 2 小时,除非备注明确说明仍在工作,否则默认视为 stale,不阻塞当前工作。

## Active Sessions

| Session | Last Seen | Status | Area | Note |
|---|---|---|---|---|
| session-id | YYYY-MM-DD HH:mm | active | startup | initialized |

## Messages

- YYYY-MM-DD HH:mm — from -> to: message

## Log

### YYYY-MM-DD HH:mm — session-id

- Did:
- Changed:
- Verified:
- Blocked:
- Next:

14. 状态查询

当用户问"记忆状态"或"当前记忆有什么"时:

  1. 检查文件是否存在。
  2. 简述每个文件当前记录的内容。
  3. 列出 active sessions,并指出超过 2 小时未更新的 session 可能 stale。
  4. 列出与当前任务相关的 open P0/P1 bugs。
  5. 指出明显过时、冗余或缺失的信息。
  6. 给出一个最有价值的清理建议。

15. 压缩规则

当记忆文件过长时:

  1. 保留当前目标、阻塞、下一步。
  2. 保留 open bugs。
  3. 保留长期 ADR。
  4. 合并旧 handoff 日志。
  5. 删除重复和过时内容。
  6. 不删除未验证 bug 或关键决策。
  7. 压缩后说明改了哪些文件。
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 470kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall