project-memory-architect

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

Project Memory Architect

Overview

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

核心价值：

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

---

Quick Start

场景1：新项目初始化

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

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

场景2：检查现有项目

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

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

场景3：模块化拆分

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

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

---

5层内存架构

详细说明见 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：分析现有配置

# 检查项目内存结构
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 忽略配置

使用方式：

# 复制整个模板目录
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 结构

# 项目名称指南

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

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

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

4. 本地配置管理

必须包含在 .gitignore：

# Claude Code 本地配置
.claude/CLAUDE.local.md

本地配置内容示例：

• 开发环境配置（Bundle ID、Team ID）
• 测试数据（API 端点、沙箱URL）
• 个人工作流偏好
• 调试设置

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

问题场景：CLAUDE.md 文件内容过多（超过 300 行）导致：

• 信息密度低，难以快速定位
• 维护成本高，修改一处需要滚动大量内容
• 主题混杂，违反单一职责原则

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

精炼流程

1. 识别可精炼的内容

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

2. 提取核心原则到主文件

   # CLAUDE.md（保持精炼）
   
   ## UI 设计规范
   
   核心哲学：放弃 = 省钱 = 好事 → 绿色；购买 = 花钱 = 破坏性 → 红色
   
   完整规范见：[UI 设计规则](rules/ui-design.md)
   

3. 创建精炼的规则文件

   # rules/ui-design.md
   
   ## 产品核心哲学
   详细的哲学解释...
   
   ## 购买按钮规范
   完整代码示例...
   
   ## 放弃按钮规范
   完整代码示例...
   
   ## 常见错误
   错误示例和正确做法...
   

4. 验证规则文件质量

   • ✅ 是否独立可读？（不依赖主文件）
   • ✅ 是否包含必要示例？
   • ✅ 是否有清晰的检查清单？
   • ✅ 是否便于快速查阅？

精炼原则

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

检查清单

创建规则文件时确认：

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

示例对比

❌ 精炼前（CLAUDE.md 过长）：

## UI 设计规范

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

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

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

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

✅ 精炼后（主文件简洁）：

## UI 设计规范

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

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

✅ 规则文件（完整详细）：

# rules/ui-design.md

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

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

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

---

常见问题

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

A: 推荐放在 .claude/CLAUDE.md，原因：

• 集中管理所有 Claude 相关文件
• 更清晰的目录结构
• 便于添加规则和其他资源

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

A: 检查以下指标：

# 文件行数
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