Project Memory 项目记忆管理（增强版）

概述

此 skill 采用增强版模块化文件结构管理项目记忆，解决两个核心问题：

上下文溢出 - 主文件保持在30行以内，详细内容分散到子文件
组件重复定义 - dev-docs/ 目录记录所有组件定义，新会话必须加载

核心设计

新会话启动
  ↓
读取 project-memory.md（<30行）
读取 dev-docs/index.md（组件索引）
  ↓
AI知道已有哪些组件，不会重复创建
  ↓
按需读取 01-06-xxx.md 详细文档

文件结构

project-root/
└── .memory/
    ├── project-memory.md          # 主文件（<30行，索引+当前计划）必需
    ├── 00-index.md                # 文件导航和快速链接
    ├── 01-project-background.md   # 项目背景（按需读取）
    ├── 02-requirements.md         # 需求方案（按需读取）
    ├── 03-dev-specs.md           # 开发规范（按需读取）
    ├── 04-tech-stack.md          # 技术栈详情（按需读取）
    ├── 05-database-schema.md     # 数据库定义（按需读取）
    ├── 06-project-structure.md   # 项目结构（按需读取）
    ├── dev-docs/                 # 开发文档（上下文必读）
    │   ├── README.md
    │   ├── index.md              # 组件/API索引
    │   ├── components/           # 公共组件文档
    │   ├── hooks/                # 自定义Hooks文档
    │   ├── utils/                # 工具函数文档
    │   ├── api/                  # API接口文档
    │   └── database/             # 数据库表定义
    └── archive/                  # 归档目录
        └── phase-1-xxx.md        # 阶段归档（含dev-docs清单）

dev-docs/ 目录说明

为什么 dev-docs 必须上下文读取？

AI在开发过程中容易重复创建已存在的组件。通过将组件定义存储在 dev-docs/ 并在新会话时加载到上下文中，AI会知道：

已存在哪些组件及其完整定义
已有哪些工具函数可用
已定义哪些API接口
数据库表结构是什么

dev-docs 内容：

每个 .md 文件记录一个组件/函数/API/表的完整定义：

# Button 组件

## 功能
通用按钮组件，支持多种变体和尺寸。

## 代码定义
```typescript
interface ButtonProps {
  variant?: 'primary' | 'secondary' | 'ghost';
  size?: 'sm' | 'md' | 'lg';
  disabled?: boolean;
  onClick?: () => void;
  children: React.ReactNode;
}

export function Button({ variant = 'primary', size = 'md', ...props }: ButtonProps) {
  // 完整实现代码
}

使用示例

<Button variant="primary" size="lg" onClick={handleClick}>
  提交
</Button>

参数说明

| 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | variant | string | 否 | 按钮样式 | | size | string | 否 | 按钮尺寸 | | ... | ... | ... | ... |

注意事项

使用 theme 中的颜色变量
支持键盘导航


### 主文件 (project-memory.md) 结构

```markdown
# 项目名称

## 项目索引
- **文件导航**: [查看详情](00-index.md)
- **项目背景**: [查看详情](01-project-background.md)
- **需求方案**: [查看详情](02-requirements.md)
- **开发规范**: [查看详情](03-dev-specs.md)
- **技术栈**: [查看详情](04-tech-stack.md)
- **数据库定义**: [查看详情](05-database-schema.md)
- **项目结构**: [查看详情](06-project-structure.md)
- **开发文档**: [查看 dev-docs/](dev-docs/)

## 当前阶段
**阶段 3: 商品管理** [进行中]
- [x] 任务1
- [x] 任务2
- [-] 任务3 (80%)
- [ ] 任务4

## 阶段历史
### 阶段 1: 初始化 [已完成]
- **完成时间**: 2024-01-10
- **主要成果**: 框架搭建完成
- **归档**: [查看详情](archive/phase-1-init.md)

## 最近更新
- **2024-01-26**: 完成xxx功能

核心原则

1. 新会话加载策略（优化版 - 低Token消耗）

新会话/跨会话恢复时：

必须读取（防止重复定义）：
✅ project-memory.md（<30行）
✅ dev-docs/index.md（精简索引，<30行）

可选读取（按需）：
- 01-project-background.md
- 02-requirements.md
- 03-dev-specs.md
- 04-tech-stack.md
- 05-database-schema.md
- 06-project-structure.md
- dev-docs/components/*.md（特定组件完整定义）

Token 优化效果： | 内容 | 优化前 | 优化后 | 降低 | |------|--------|--------|------| | dev-docs/index.md | ~100行 | ~30行 | -70% | | 主加载总行数 | ~130行 | ~60行 | -54% |

按需加载原则：

index.md 仅包含：名称 + 一句话描述
完整定义存储在 dev-docs/{category}/{name}.md
需要时显式请求："查看 Button 组件完整定义"

2. dev-docs 更新规则

创建新组件时：

先在 dev-docs/components/ 创建文档
然后在项目中实现组件
保持文档和代码同步

修改现有组件时：

先更新 dev-docs/components/xxx.md
然后修改组件代码

3. 智能归档

归档阶段时，自动收集 dev-docs/ 中的内容清单：

## 开发文档清单

### 公共组件 (5个)
- [Button](../dev-docs/components/Button.md)
- [Card](../dev-docs/components/Card.md)
- ...

### 数据库表 (3个)
- [users](../dev-docs/database/users.md)
- [products](../dev-docs/database/products.md)
- ...

使用场景

场景 1: 初始化项目记忆

用户: "初始化项目记忆"

Agent 操作:

检查 .memory/ 目录是否存在
创建增强版文件结构：
- 8个主文件（project-memory.md + 00-index.md + 01-06-xxx.md）
- dev-docs/ 目录（5个子目录 + README + index）
- archive/ 目录
向用户展示创建结果
说明 dev-docs/ 的使用方法

场景 2: 新会话恢复（加载dev-docs）

用户: （新会话）"继续开发"

Agent 操作:

读取 .memory/project-memory.md（<30行）
读取 .memory/dev-docs/index.md（组件索引）

向用户汇报：

📁 项目：电商后台系统
📍 当前阶段：商品管理（80%）
📦 已有组件：Button, Card, Modal, Table（4个）
🔧 已有工具：formatDate, useAuth, fetchAPI（3个）

当前任务：
- [x] 商品CRUD
- [x] 图片上传
- [-] 库存管理（80%）
- [ ] 搜索功能

如需查看以下内容，请告诉我：
• 详细需求文档
• 开发规范约定
• 特定组件定义
• 数据库表结构

场景 3: 创建新组件

用户: "创建一个登录表单组件"

Agent 操作:

检查 dev-docs/components/ 中是否已有类似组件
如果没有：
- 在 dev-docs/components/LoginForm.md 中记录组件定义
- 在项目中实现 LoginForm 组件
向用户说明："已在 dev-docs 中记录该组件，防止后续重复创建"

场景 4: 归档已完成阶段

用户: "归档阶段2"

Agent 操作:

执行归档脚本
自动收集当前 dev-docs/ 中的内容清单
创建包含组件清单的归档文件
更新主文件中的阶段历史

核心操作

1. 初始化项目记忆

脚本: init_memory.py

创建的文件（共8个主文件 + dev-docs目录）：

project-memory.md（主文件，<30行）
00-index.md（文件导航）
01-06-xxx.md（6个详细文档）
dev-docs/README.md（开发文档说明）
dev-docs/index.md（组件索引）
dev-docs/ 下的5个子目录

2. 读取项目记忆

脚本: read_memory.py

默认读取（防止重复定义）：

python scripts/read_memory.py
# 读取 project-memory.md + dev-docs/index.md

读取特定模块：

python scripts/read_memory.py --module 02-requirements

3. 更新项目记忆

脚本: update_memory.py

支持更新主文件或特定子文件。

自动更新 dev-docs 索引：

当在 dev-docs/ 目录下新增或修改组件、API、数据库表等文件后，运行以下命令更新索引：

# 扫描 dev-docs/ 目录并自动更新 index.md
python scripts/update_memory.py index

索引更新规则：

自动扫描 dev-docs/components/、hooks/、utils/、api/、database/ 目录
从每个 .md 文件的第一段非标题内容提取描述
生成包含链接的精简索引列表
没有文档的类别显示"暂无"

使用场景：

# 1. 创建新组件文档后
echo "# NewComponent..." > dev-docs/components/NewComponent.md
python scripts/update_memory.py index

# 2. 添加 API 文档后
echo "# /api/new-api..." > dev-docs/api/new-api.md
python scripts/update_memory.py index

# 3. 修改组件描述后（重新提取描述）
vim dev-docs/components/Button.md
python scripts/update_memory.py index

4. 归档阶段

脚本: archive_phase.py

# 归档阶段
python scripts/archive_phase.py archive --phase 2 --name "认证系统" --summary "完成JWT认证和权限管理"

# 查看归档列表
python scripts/archive_phase.py list

归档文件自动包含：

阶段总结
任务完成情况
dev-docs清单（组件、hooks、utils、API、数据库表）
技术决策记录

最佳实践

上下文管理

新会话必须读取 dev-docs/index.md - 防止重复创建组件
按需读取详细文档 - 避免加载不需要的内容
更新时同步更新 dev-docs - 保持文档和代码一致
定期归档已完成阶段 - 保持主文件精简

文件大小控制

| 文件 | 建议大小 | 说明 | |------|----------|------| | project-memory.md | <30行 | 主文件，轻量 | | dev-docs/index.md | <100行 | 组件索引 | | dev-docs/components/.md | <150行 | 单个组件文档 | | dev-docs/database/.md | <100行 | 单表定义 | | 01-06-xxx.md | <200行 | 详细文档 | | archive/*.md | 不限 | 历史归档 |

跨会话恢复策略

新会话开始
  ↓
读取 project-memory.md（<30行）
读取 dev-docs/index.md（组件索引）
  ↓
汇报：项目名、当前阶段、已有组件、待办任务
  ↓
询问：是否需要详细背景/需求/特定组件定义？
  ↓
（用户明确需求后）按需读取子文件

示例对话

示例 1: 新会话恢复（加载dev-docs）

用户: （新会话）"继续开发电商项目"

Agent:

已读取项目记忆：

📁 项目：电商后台管理系统
📍 当前阶段：商品管理（阶段 3，80%）
📦 已有组件：Button, Card, Modal, Table, Form（5个）
🔧 已有Hooks：useAuth, useFetch, useModal（3个）
🛠️ 已有工具：formatDate, debounce, validate（3个）
🗄️ 已有数据库表：users, products, orders（3个）

当前进行中的任务：
- [x] 商品CRUD接口
- [x] 图片上传功能
- [-] 库存管理系统（80%）
- [ ] 商品搜索功能
- [ ] 批量操作功能

最近更新：
- 今天 14:30: 完成库存管理核心逻辑
- 昨天: 图片上传功能上线

---
如需查看以下内容，请告诉我：
• 项目背景详情
• 需求方案文档
• 开发规范约定
• 特定组件完整定义（如 Button 组件参数）
• 数据库表结构详情

示例 2: 创建新组件（检查dev-docs）

用户: "创建一个日期选择器组件"

Agent:

检查 dev-docs/components/... 发现已有：
- Button, Card, Modal, Table, Form

未找到日期选择器组件，开始创建：

1. 在 dev-docs/components/DatePicker.md 记录组件定义
2. 实现 DatePicker 组件代码
3. 更新 dev-docs/index.md 索引

✅ 已完成！组件定义已记录，后续会话将知道该组件存在。

辅助脚本

所有脚本位于 scripts/ 目录：

init_memory.py

初始化增强版项目记忆结构（8个主文件 + dev-docs目录）

read_memory.py

智能读取项目记忆

默认读取 project-memory.md + dev-docs/index.md
--module 参数读取特定子文件
--list 查看可用模块

update_memory.py

更新项目记忆，自动判断更新哪个文件

archive_phase.py

归档已完成阶段，自动收集dev-docs清单

python scripts/archive_phase.py archive --phase 2 --name "xxx" --summary "xxx"

project memory skill

Project Memory 项目记忆管理（增强版）

概述

核心设计

文件结构

dev-docs/ 目录说明

使用示例

参数说明

注意事项

核心原则

1. 新会话加载策略（优化版 - 低Token消耗）

2. dev-docs 更新规则

3. 智能归档

使用场景

场景 1: 初始化项目记忆

场景 2: 新会话恢复（加载dev-docs）

场景 3: 创建新组件

场景 4: 归档已完成阶段

核心操作

1. 初始化项目记忆

2. 读取项目记忆

3. 更新项目记忆

4. 归档阶段

最佳实践

上下文管理

文件大小控制

跨会话恢复策略

示例对话

示例 1: 新会话恢复（加载dev-docs）

示例 2: 创建新组件（检查dev-docs）

辅助脚本

init_memory.py

read_memory.py

update_memory.py

archive_phase.py