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。仅用于初始化、记忆状态查询、压缩清理。默认中文。

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

# project-memory-cn

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

目标是让新 session 快速知道:

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

核心原则:

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

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

---

## 1. 目标结构

在仓库根目录维护:

```text
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 启动时创建唯一代号:

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

示例:

```text
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

```markdown
@AGENTS.md
```

---

### 13.2 AGENTS.md

```markdown
# 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

```markdown
# 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

```markdown
# 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

```markdown
# Current State

## Goal

-

## Now

-

## Progress

- [ ]

## Blockers

- None

## Next

1.

## Workstreams

- default: unassigned / idle / -

## Last Updated

-
```

---

### 13.7 .mem/decisions.md

```markdown
# 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

```markdown
# 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: 471kUpdated 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