# Project Memory Architect

> 分析和优化项目内存架构（Claude Code 项目配置指南）。使用场景：(1) 新建项目时初始化符合规范的 .claude/ 目录结构，(2) 检查现有项目内存配置并提供优化建议，(3) 模块化拆分大型 CLAUDE.md 文件，(4) 创建规则文件（rules/）提升可维护性。检测项目根目录、分析配置文件、提供5层内存架构建议（企业策略/项目内存/项目规则/用户内存/项目本地内存）。

- Skill: `ssdiwu/project-memory-architect` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add ssdiwu/project-memory-architect`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ssdiwu/project-memory-architect/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: ssdiwu (https://skillmd.com/u/ssdiwu)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/ssdiwu/project-memory-architect

---


# Project Memory Architect

## Overview

帮助项目建立符合 Claude Code 官方规范的内存架构，通过5层内存系统（企业策略、项目内存、项目规则、用户内存、项目本地内存）提升代码可维护性和团队协作效率。

**核心价值**：
- 🎯 **规范化**：遵循官方推荐的5层内存架构
- 📦 **模块化**：拆分大型文件为规则目录，提升可维护性
- 🔒 **隔离性**：本地配置与团队配置分离
- 🚀 **可复用**：提供模板快速启动新项目

---

## Quick Start

### 场景1：新项目初始化

```bash
# 用户说
"我要开始一个新项目"
"初始化项目配置"
"设置项目内存架构"

# 你应该
1. 检测是否已有 .claude/ 目录
2. 从 assets/templates/ 复制模板结构
3. 根据项目类型定制规则文件
4. 创建 .gitignore 忽略本地配置
```

### 场景2：检查现有项目

```bash
# 用户说
"检查项目配置"
"优化项目结构"
"看看项目内存是否规范"

# 你应该
1. 读取 .claude/ 目录结构
2. 分析 CLAUDE.md 大小（超过500行需拆分）
3. 检查是否有规则文件（rules/）
4. 提供优化建议
```

### 场景3：模块化拆分

```bash
# 用户说
"把 CLAUDE.md 拆分成规则文件"
"优化项目内存结构"
"模块化项目配置"

# 你应该
1. 分析 CLAUDE.md 内容主题
2. 识别可拆分的主题块（如：编码规范、工作流、产品哲学）
3. 创建规则文件
4. 更新主 CLAUDE.md 引用规则
```

---

## 5层内存架构

详细说明见 [references/memory-types.md](references/memory-types.md)

### 快速参考

| 层级 | 位置 | 用途 | 共享对象 |
|------|------|------|----------|
| **1. 企业策略** | `/Library/Application Support/ClaudeCode/CLAUDE.md` | 组织级规范 | 全组织 |
| **2. 项目内存** | `.claude/CLAUDE.md` | 项目特定知识 | 团队 |
| **3. 项目规则** | `.claude/rules/*.md` | 模块化主题指南 | 团队 |
| **4. 用户内存** | `~/.claude/CLAUDE.md` | 个人偏好 | 仅你 |
| **5. 项目本地** | `.claude/CLAUDE.local.md` | 个人项目配置 | 仅你（当前项目）|

**关键原则**：
- 项目本地配置（CLAUDE.local.md）必须加入 .gitignore
- 规则文件用于模块化拆分（>200行时考虑）
- 后加载的内存覆盖先加载的（优先级：本地 > 用户 > 规则 > 项目）

---

## 工作流程

### 步骤1：分析现有配置

```bash
# 检查项目内存结构
ls -la .claude/

# 检查文件大小
wc -l .claude/CLAUDE.md

# 判断是否需要拆分
if [ $(wc -l < .claude/CLAUude.md) -gt 500 ]; then
    echo "建议拆分为规则文件"
fi
```

### 步骤2：识别优化机会

**检查清单**：
- [ ] 是否有 .claude/ 目录？
- [ ] CLAUDE.md 是否超过 500 行？
- [ ] 是否有明确的主题边界（编码规范、工作流、产品哲学）？
- [ ] 是否有 CLAUDE.local.md？
- [ ] .gitignore 是否忽略本地配置？

### 步骤3：提供优化方案

**场景A：缺少 .claude/ 目录**
```
建议：初始化项目内存架构
1. 创建 .claude/ 目录
2. 复制模板从 assets/templates/
3. 根据项目定制内容
```

**场景B：CLAUDE.md 过大**
```
建议：模块化拆分为规则文件
当前行数：850行
建议拆分：
- .claude/rules/swift-conventions.md（编码规范）
- .claude/rules/task-workflow.md（任务流程）
- .claude/rules/product-philosophy.md（产品哲学）
```

**场景C：缺少本地配置**
```
建议：创建 CLAUDE.local.md
用途：个人开发配置、测试数据、调试设置
⚠️ 记得加入 .gitignore
```

---

## 模板资源

### assets/templates/

包含完整的模板目录结构：

```
templates/
├── .claude/
│   ├── CLAUDE.local.md    # 本地配置模板
│   └── rules/             # 规则文件模板
│       ├── swift-conventions.md
│       ├── task-workflow.md
│       ├── product-philosophy.md
│       └── documentation-sync.md
└── .gitignore            # Git 忽略配置
```

**使用方式**：
```bash
# 复制整个模板目录
cp -r assets/templates/. .claude/

# 根据项目编辑模板
vim .claude/rules/swift-conventions.md
```

---

## 决策树：如何选择内存类型？

```
开始
  ↓
组织级规范吗？ → 是 → 企业策略
  ↓ 否
项目特定吗？ → 是 → 敏感/个人配置？
  ↓            ↓ 是      ↓ 否
个人偏好吗？ → 是 → CLAUDE.local.md → CLAUDE.md 或 rules/
  ↓ 否                  (加入.gitignore)
用户内存 (~/.claude/)
```

---

## 最佳实践

### 1. 何时拆分规则文件？

满足以下**任一条件**时：
- 文件超过 200 行
- 有明确的主题边界
- 不同任务需要不同知识
- 需要单独维护更新

### 2. 规则文件命名规范

- 使用小写字母和连字符：`swift-conventions.md`
- 名称应清晰表达主题：`task-workflow.md`
- 避免通用名称：不用 `rules.md`，用 `testing-guidelines.md`

### 3. 主 CLAUDE.md 结构

```markdown
# 项目名称指南

## 快速参考
- 规则文件索引
- 快速启动指南

## 核心原则
（不可拆分的核心内容）

## 规则文件
见 .claude/rules/:
- [编码规范](rules/swift-conventions.md)
- [任务流程](rules/task-workflow.md)
- [产品哲学](rules/product-philosophy.md)
```

### 4. 本地配置管理

**必须包含在 .gitignore**：
```gitignore
# Claude Code 本地配置
.claude/CLAUDE.local.md
```

**本地配置内容示例**：
- 开发环境配置（Bundle ID、Team ID）
- 测试数据（API 端点、沙箱URL）
- 个人工作流偏好
- 调试设置

### 5. 精炼文档到规则文件（重要）

**问题场景**：CLAUDE.md 文件内容过多（超过 300 行）导致：
- 信息密度低，难以快速定位
- 维护成本高，修改一处需要滚动大量内容
- 主题混杂，违反单一职责原则

**解决方案**：将详细内容精炼后移至 rules/ 规则文件

#### 精炼流程

1. **识别可精炼的内容**
   - 查找包含大量代码示例的章节
   - 识别独立主题（如 UI 设计、编码规范）
   - 标记过于详细的说明性内容

2. **提取核心原则到主文件**
   ```markdown
   # CLAUDE.md（保持精炼）

   ## UI 设计规范

   核心哲学：放弃 = 省钱 = 好事 → 绿色；购买 = 花钱 = 破坏性 → 红色

   完整规范见：[UI 设计规则](rules/ui-design.md)
   ```

3. **创建精炼的规则文件**
   ```markdown
   # rules/ui-design.md

   ## 产品核心哲学
   详细的哲学解释...

   ## 购买按钮规范
   完整代码示例...

   ## 放弃按钮规范
   完整代码示例...

   ## 常见错误
   错误示例和正确做法...
   ```

4. **验证规则文件质量**
   - ✅ 是否独立可读？（不依赖主文件）
   - ✅ 是否包含必要示例？
   - ✅ 是否有清晰的检查清单？
   - ✅ 是否便于快速查阅？

#### 精炼原则

| 原则 | 说明 | 示例 |
|------|------|------|
| **核心保留** | 主文件保留核心原则和快速参考 | "购买按钮用红色" |
| **详细下移** | 详细示例和代码移至规则文件 | 完整按钮实现代码 |
| **交叉引用** | 主文件引用具体规则文件 | "完整规范见 rules/ui-design.md" |
| **单一职责** | 每个规则文件只负责一个主题 | ui-design.md 只讲 UI 设计 |

#### 检查清单

创建规则文件时确认：
- [ ] 规则文件是否独立可读？
- [ ] 主文件是否保留了核心原则？
- [ ] 是否有明确的交叉引用？
- [ ] 文件名是否清晰表达主题？
- [ ] 是否减少了主文件的行数至少 50 行？

#### 示例对比

**❌ 精炼前（CLAUDE.md 过长）**：
```markdown
## UI 设计规范

### 产品核心哲学
CoolDown 的产品目的是...（200字）

### 购买按钮
完整代码示例（30行）

### 放弃按钮
完整代码示例（30行）

### 其他按钮
表格和更多示例（40行）
```

**✅ 精炼后（主文件简洁）**：
```markdown
## UI 设计规范

**核心哲学**：放弃=省钱=好事（绿色），购买=花钱=破坏性（红色）

完整规范：[UI 设计规则](rules/ui-design.md)
```

**✅ 规则文件（完整详细）**：
```markdown
# rules/ui-design.md

## 产品核心哲学
（详细解释 + 完整代码示例）

## 按钮规范
（所有按钮类型 + 代码示例）

## 检查清单
（5 项检查点）
```

---

## 常见问题

### Q: 项目内存应该在根目录还是 .claude/ 目录？

**A**: 推荐放在 `.claude/CLAUDE.md`，原因：
- 集中管理所有 Claude 相关文件
- 更清晰的目录结构
- 便于添加规则和其他资源

### Q: 如何判断是否需要拆分规则？

**A**: 检查以下指标：
```bash
# 文件行数
wc -l .claude/CLAUDE.md

# 主题数量
grep -E "^## " .claude/CLAUDE.md | wc -l

# 如果行数 > 200 且主题数 > 5，建议拆分
```

### Q: 规则文件和参考文档有什么区别？

**A**:
- **规则文件**（rules/）：项目特定的规范和流程，精简且可执行
- **参考文档**（references/）：详细的技术文档、API 文档、架构说明

规则文件是"做什么"，参考文档是"怎么做的细节"。

---

## 资源

### references/memory-types.md
5层内存架构的详细说明，包括：
- 每层的用途和适用场景
- 决策树和最佳实践
- 常见问题解答
- 模板快速启动指南

**何时阅读**：需要深入理解内存架构时

### assets/templates/
完整的模板目录结构，包含：
- CLAUDE.local.md 模板
- 4个规则文件模板（以 CoolDown 项目为例）
- .gitignore 配置

**何时使用**：初始化新项目或重构现有项目时

---

**维护者**: Claude Code Community
**最后更新**: 2026-01-13