Claude Code 结构化笔记技术详解

结构化笔记是一种强大的技术，Claude 定期将笔记写入在上下文窗口之外持久化的文件中。这些笔记可以在需要时检索，提供持久化记忆并随着时间推移建立机构知识。

结构化笔记的重要性

持久化记忆方面，与在窗口填满时丢失的上下文不同，笔记在会话和压缩之间保持持久。最小开销方面，笔记只在相关时加载，保持活动上下文的清洁。渐进式构建方面，信息随时间累积，建立针对项目的知识库。上下文恢复方面，在上下文重置后，Claude 可以读取自己的笔记并无缝继续。知识转移方面，团队成员可以通过维护良好的笔记理解项目历史和决策。

有效的笔记模式

上下文保持

使用临时文件在会话或主题之间转换时保持当前上下文。工作内存方式是创建一个在整个会话中更新的 CURRENT_SESSION.md 文件，可以在以后引用。上下文桥接方式是创建摘要文件，捕获从一个会话到下一个会话的基本上下文。

这种方法允许开始新会话同时保持连续性，引用以前的工作而不混乱当前上下文，构建项目演进的时间线，从上下文窗口限制无缝恢复。

实际应用示例

CURRENT_SESSION.md 模板

# Current Session: 用户认证系统开发
**日期**: 2025-11-04
**会话目标**: 实现基于 JWT 的用户认证系统

## 当前状态
- ✅ 完成了用户模型设计
- ✅ 实现了密码哈希功能
- 🔄 正在开发 JWT 令牌生成
- ⏳ 待实现：刷新令牌机制

## 关键决策
1. 使用 bcrypt 进行密码哈希，轮数设置为 12
2. JWT 有效期设置为 15 分钟
3. 刷新令牌有效期设置为 7 天
4. 使用 Redis 存储令牌黑名单

## 当前文件位置
- 用户模型: `src/models/User.js`
- 认证中间件: `src/middleware/auth.js`
- 令牌服务: `src/services/tokenService.js`

## 下一步行动
1. 实现令牌刷新端点
2. 添加登出功能
3. 编写单元测试
4. 更新 API 文档

## 遇到的问题
- Redis 连接配置需要优化
- 需要处理令牌过期边界情况

上下文桥接示例

MIGRATION_CONTEXT.md

# 数据库迁移上下文
**迁移版本**: v2.1.0 → v2.2.0
**执行日期**: 2025-11-04
**负责人**: 开发团队

## 迁移概述
将用户认证从 Session-based 迁移到 JWT-based 系统。

## 前置条件
- 备份数据库
- 停止应用服务
- 确认 Redis 服务可用

## 迁移步骤

### 1. 数据库结构变更
```sql
-- 添加令牌相关字段
ALTER TABLE users ADD COLUMN refresh_token VARCHAR(500);
ALTER TABLE users ADD COLUMN token_expires_at TIMESTAMP;

-- 创建令牌黑名单表
CREATE TABLE token_blacklist (
    id SERIAL PRIMARY KEY,
    token_hash VARCHAR(64) UNIQUE NOT NULL,
    expires_at TIMESTAMP NOT NULL,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

2. 数据迁移

// scripts/migrateAuth.js
const bcrypt = require('bcrypt');
const { User } = require('../src/models');

async function migrateUsers() {
    const users = await User.findAll();

    for (const user of users) {
        // 生成刷新令牌
        const refreshToken = generateRefreshToken();
        const tokenHash = await bcrypt.hash(refreshToken, 12);

        await user.update({
            refresh_token: tokenHash,
            token_expires_at: new Date(Date.now() + 7 * 24 * 60 * 60 * 1000)
        });
    }
}

3. 配置更新

// config/auth.js
module.exports = {
    jwt: {
        secret: process.env.JWT_SECRET,
        expiresIn: '15m',
        refreshExpiresIn: '7d'
    },
    redis: {
        host: process.env.REDIS_HOST,
        port: process.env.REDIS_PORT,
        password: process.env.REDIS_PASSWORD
    }
};

回滚计划

-- 回滚数据库变更
ALTER TABLE users DROP COLUMN refresh_token;
ALTER TABLE users DROP COLUMN token_expires_at;
DROP TABLE token_blacklist;

验证步骤

1. 验证用户可以正常登录
2. 测试令牌刷新功能
3. 确认登出功能正常
4. 检查令牌黑名单机制

### 决策日志示例

#### DECISIONS.md

```markdown
# 项目决策记录

## 2025-11-04

### 决策 #012: 选择 JWT 作为认证机制
**状态**: 已接受
**决策者**: 开发团队
**影响范围**: 认证系统、API 设计、前端状态管理

#### 背景
需要为新的微服务架构选择认证机制。当前系统使用基于 Session 的认证，但在微服务环境中存在扩展性问题。

#### 考虑的选项
1. **JWT (JSON Web Tokens)**
   - 优点: 无状态、跨域支持、移动端友好
   - 缺点: 令牌大小、撤销复杂性

2. **OAuth 2.0 + OpenID Connect**
   - 优点: 标准化、第三方集成
   - 缺点: 复杂度高、学习曲线陡峭

3. **Session + Redis**
   - 优点: 简单、易于撤销
   - 缺点: 有状态、扩展性限制

#### 最终决策
选择 JWT 作为主要认证机制，配合 Redis 实现令牌撤销功能。

#### 理由
- 微服务架构需要无状态认证
- 团队对 JWT 有一定经验
- 前端应用需要跨域支持
- 移动端集成需求

#### 实施计划
1. 实现基础 JWT 认证 (本周)
2. 添加刷新令牌机制 (下周)
3. 集成 Redis 令牌黑名单 (下周)
4. 更新前端认证流程 (下下周)

#### 风险缓解
- 令牌大小通过最小化 payload 来控制
- 撤销问题通过 Redis 黑名单解决
- 安全性通过短有效期 + 刷新令牌来保证

---

### 决策 #011: 数据库选择 PostgreSQL
**状态**: 已接受
**日期**: 2025-10-28
**影响**: 数据持久化层、查询优化、团队技能发展

[之前决策的详细记录...]

架构决策记录 (ADR) 示例

ADR-001: 使用 PostgreSQL 作为主数据库

# ADR-001: Use PostgreSQL for Primary Database

## Status
Accepted

## Context
我们需要为新的微服务选择数据库，该服务将处理用户数据、交易和报告。该服务期望高读写吞吐量，并且需要 ACID 合规性。

## Decision
我们将使用 PostgreSQL 作为主数据库。

## Consequences

### Positive
- 强大的 ACID 合规性和可靠性
- 复杂查询的出色性能
- 丰富的生态系统和工具
- 团队熟悉度

### Negative
- 与 NoSQL 替代品相比，运营复杂性更高
- 与分布式数据库相比，扩展性限制
- 额外的基础设施要求

## Alternatives Considered

- **MongoDB**: 由于一致性问题被拒绝
- **MySQL**: 由于 JSON 处理限制被拒绝
- **DynamoDB**: 由于查询灵活性需求被拒绝

## Implementation Details

### 连接配置
```javascript
// config/database.js
const { Pool } = require('pg');

const pool = new Pool({
    host: process.env.DB_HOST,
    port: process.env.DB_PORT,
    database: process.env.DB_NAME,
    user: process.env.DB_USER,
    password: process.env.DB_PASSWORD,
    max: 20,
    idleTimeoutMillis: 30000,
    connectionTimeoutMillis: 2000,
});

迁移策略

// migrations/001_initial_schema.sql
CREATE EXTENSION IF NOT EXISTS "uuid-ossp";

CREATE TABLE users (
    id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
    username VARCHAR(50) UNIQUE NOT NULL,
    email VARCHAR(100) UNIQUE NOT NULL,
    password_hash VARCHAR(255) NOT NULL,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

CREATE INDEX idx_users_email ON users(email);
CREATE INDEX idx_users_username ON users(username);

Related Decisions

• ADR-002: 数据库备份策略
• ADR-003: 查询性能优化

Notes

考虑在将来添加只读副本以提高读取性能。

### 学习笔记示例

#### LEARNINGS.md

```markdown
# 项目学习笔记

## 性能优化模式

### 数据库查询优化
**发现**: N+1 查询问题严重影响 API 性能
**解决方案**: 使用数据预加载和查询优化
```javascript
// 优化前
const users = await User.findAll();
for (const user of users) {
    const posts = await user.getPosts(); // N+1 问题
}

// 优化后
const users = await User.findAll({
    include: [{
        model: Post,
        as: 'posts'
    }]
});

缓存策略

学到的模式: 多层缓存架构

// 1. 内存缓存 (最快)
const cache = new Map();

// 2. Redis 缓存 (中等)
const redis = require('redis');
const client = redis.createClient();

// 3. 数据库查询 (最慢)
async function getUser(id) {
    // 检查内存缓存
    if (cache.has(id)) return cache.get(id);

    // 检查 Redis 缓存
    const cached = await client.get(`user:${id}`);
    if (cached) {
        const user = JSON.parse(cached);
        cache.set(id, user);
        return user;
    }

    // 查询数据库
    const user = await User.findByPk(id);
    await client.setex(`user:${id}`, 3600, JSON.stringify(user));
    cache.set(id, user);
    return user;
}

常见陷阱

异步处理陷阱

问题: 忘记使用 await 导致的未处理 Promise

// ❌ 错误示例
function updateUser(id, data) {
    User.update(data, { where: { id } }); // 忘记 await
}

// ✅ 正确示例
async function updateUser(id, data) {
    await User.update(data, { where: { id } });
}

环境配置陷阱

问题: 硬编码配置值

// ❌ 错误示例
const dbUrl = 'postgresql://user:pass@localhost:5432/mydb';

// ✅ 正确示例
const dbUrl = process.env.DATABASE_URL;

最佳实践

错误处理模式

// 统一错误处理中间件
const errorHandler = (err, req, res, next) => {
    const statusCode = err.statusCode || 500;
    const message = process.env.NODE_ENV === 'production'
        ? 'Internal Server Error'
        : err.message;

    res.status(statusCode).json({
        status: 'error',
        statusCode,
        message,
        ...(process.env.NODE_ENV === 'development' && { stack: err.stack })
    });
};

日志记录模式

const winston = require('winston');

const logger = winston.createLogger({
    level: 'info',
    format: winston.format.combine(
        winston.format.timestamp(),
        winston.format.json()
    ),
    transports: [
        new winston.transports.File({ filename: 'error.log', level: 'error' }),
        new winston.transports.File({ filename: 'combined.log' })
    ]
});

// 使用示例
logger.info('User login successful', { userId: user.id, ip: req.ip });
logger.error('Database connection failed', { error: err.message });

外部资源

有用的库和工具

• bcrypt: 密码哈希
• jsonwebtoken: JWT 令牌处理
• joi: 数据验证
• winston: 日志记录
• helmet: 安全中间件

文档链接

• Express.js 最佳实践
• Node.js 安全指南
• PostgreSQL 性能优化

### 故障排除指南示例

#### TROUBLESHOOTING.md

```markdown
# 故障排除指南

## 常见问题及解决方案

### 1. 数据库连接问题

#### 症状

Error: connect ECONNREFUSED 127.0.0.1:5432

#### 解决步骤
1. 检查 PostgreSQL 服务状态
```bash
# macOS
brew services list | grep postgresql
brew services start postgresql

# Ubuntu
sudo systemctl status postgresql
sudo systemctl start postgresql

2. 验证连接参数

console.log({
    host: process.env.DB_HOST,
    port: process.env.DB_PORT,
    database: process.env.DB_NAME
});

3. 测试连接

psql -h localhost -p 5432 -U username dbname

2. 内存泄漏问题

症状

• 应用内存使用持续增长
• 响应时间逐渐变慢
• 最终应用崩溃

调试步骤

// 添加内存监控
const used = process.memoryUsage();
console.log({
    rss: Math.round(used.rss / 1024 / 1024 * 100) / 100,
    heapTotal: Math.round(used.heapTotal / 1024 / 1024 * 100) / 100,
    heapUsed: Math.round(used.heapUsed / 1024 / 1024 * 100) / 100,
    external: Math.round(used.external / 1024 / 1024 * 100) / 100
});

// 检查事件监听器泄漏
console.log('Event listeners:', process.listenerCount('exit'));

常见原因和解决方案

// ❌ 问题：未清理的定时器
setInterval(() => {
    // 一些操作
}, 1000);

// ✅ 解决：保存引用并清理
const intervals = [];
const timer = setInterval(() => {
    // 一些操作
}, 1000);
intervals.push(timer);

// 应用关闭时清理
process.on('SIGINT', () => {
    intervals.forEach(clearInterval);
    process.exit(0);
});

3. CORS 问题

症状

Access to XMLHttpRequest at 'http://localhost:3000/api/users'
from origin 'http://localhost:8080' has been blocked by CORS policy

解决方案

// 安装 cors 中间件
npm install cors

// 基础配置
const cors = require('cors');
app.use(cors());

// 或自定义配置
app.use(cors({
    origin: ['http://localhost:8080', 'https://yourdomain.com'],
    credentials: true,
    methods: ['GET', 'POST', 'PUT', 'DELETE'],
    allowedHeaders: ['Content-Type', 'Authorization']
}));

4. JWT 令牌问题

症状

JsonWebTokenError: invalid signature

调试步骤

// 1. 验证令牌格式
const jwt = require('jsonwebtoken');

function debugToken(token) {
    try {
        const decoded = jwt.decode(token, { complete: true });
        console.log('Token header:', decoded.header);
        console.log('Token payload:', decoded.payload);

        // 验证签名
        const verified = jwt.verify(token, process.env.JWT_SECRET);
        console.log('Token is valid:', verified);
    } catch (error) {
        console.error('Token error:', error.message);
    }
}

常见问题

• 密钥不匹配: 确保所有环境使用相同的 JWT_SECRET
• 令牌过期: 检查令牌的 exp 字段
• 格式错误: 确保令牌没有多余的空格或换行符

环境特定问题

开发环境

Node.js 版本兼容性

# 检查当前版本
node --version
npm --version

# 使用 nvm 管理版本
nvm install 18.17.0
nvm use 18.17.0
nvm alias default 18.17.0

端口冲突

# 查找占用端口的进程
lsof -i :3000

# 终止进程
kill -9 <PID>

# 或在代码中使用动态端口
const PORT = process.env.PORT || 3000;

生产环境

PM2 进程管理

# 查看进程状态
pm2 status

# 查看日志
pm2 logs app-name

# 重启应用
pm2 restart app-name

# 监控模式
pm2 monit

SSL 证书问题

// 验证证书配置
const fs = require('fs');
const https = require('https');

const options = {
    key: fs.readFileSync('/path/to/private.key'),
    cert: fs.readFileSync('/path/to/certificate.crt')
};

// 测试 HTTPS 服务器
https.createServer(options, (req, res) => {
    res.writeHead(200);
    res.end('SSL working!');
}).listen(443);

调试工具和命令

内存分析

# 生成堆快照
node --inspect index.js

# 使用 Chrome DevTools 分析
# 在 Chrome 中打开 chrome://inspect

性能监控

# 安装 clinic.js
npm install -g clinic

# 性能分析
clinic doctor -- node index.js

# 火焰图分析
clinic flame -- node index.js

日志分析

# 实时查看日志
tail -f logs/combined.log

# 搜索错误日志
grep "ERROR" logs/combined.log

# 分析访问模式
awk '{print $1}' logs/access.log | sort | uniq -c | sort -nr

决策日志

维护 DECISIONS.md 来记录决策内容和时间、每个决策背后的基本原理、考虑的替代方法、对系统其他部分的影响、参与决策的人员。这种系统化的决策记录方法确保了重要决策的可追溯性和透明度。

架构决策记录

对重要的架构决策使用 ADR 格式，人类和 AI 代理都可以轻松理解和引用。ADR 模板包括状态、上下文、决策、后果、考虑的替代方案等部分。

ADR 为 AI 代理提供了多种好处：结构化上下文提供一致的、可扫描的决策上下文；历史推理使代理能够理解过去决策的原因；影响评估使清晰的后果帮助代理评估相关变更；一致性使标准化格式使信息易于解析。

学习笔记

保持 LEARNINGS.md 来记录在此代码库中运行良好的模式、发现的常见陷阱、性能考虑、项目特定的最佳实践、外部资源和参考资料。这种持续学习的方法确保了知识的积累和传承。

故障排除指南

使用常见问题及其解决方案、证明有效的调试步骤、环境特定的问题、配置陷阱和修复来记录 TROUBLESHOOTING.md。这种系统化的故障排除方法减少了重复问题的解决时间。

实施技巧

具体化

包含具体细节、文件路径和特定方法，而不是模糊的描述。具体的描述使笔记更有用和可操作。

定期更新

在完成重要任务或做出重要发现后更新笔记。定期维护确保笔记的相关性和准确性。

结构化格式

使用一致的标题、项目符号和组织以便于扫描。结构化的格式使信息更容易理解和导航。

交叉引用

在不同笔记文件之间链接并引用特定的代码位置。交叉引用创建了知识网络，使相关信息更容易找到。

时间戳

为时间敏感信息包含时间戳。时间戳提供了重要的上下文，并帮助跟踪信息的演进。

示例提供

在相关的地方提供具体的代码示例和命令片段。示例使抽象概念更容易理解和应用。

实践中的好处

这种方法通过维护连续性，会话可以准确地在它们停止的地方继续；构建专业知识，知识累积而不是丢失；提高效率，减少重新解释上下文的时间；创建文档，笔记作为团队的活文档；支持调试，历史上下文帮助识别根本原因，从而改变了 Claude 处理复杂多会话项目的方式。

知识管理策略

有效的结构化笔记需要系统性的方法。建立清晰的文件组织结构，确保笔记容易找到和维护。使用一致的命名约定和格式标准，提高笔记的可读性和可用性。

定期审查和更新笔记内容，确保它们反映当前的项目状态和最佳实践。通过版本控制跟踪笔记的变更，维护知识演进的历史记录。

鼓励团队成员贡献和维护笔记，建立集体知识库。通过定期的知识分享会议，确保团队成员了解和利用可用的笔记资源。

工具集成

结构化笔记可以与各种开发工具和工作流程集成。使用 IDE 插件或扩展来快速访问和编辑笔记。集成笔记系统到 CI/CD 流水线中，自动记录重要的构建和部署信息。

利用搜索和索引工具快速找到相关信息。使用标签和分类系统组织笔记，提高检索效率。

长期价值

结构化笔记不仅在当前项目中提供价值，还为未来的项目建立了知识基础。通过记录成功模式、失败教训和最佳实践，团队可以避免重复错误，加速新项目的启动。

笔记成为组织知识资产的重要组成部分，支持团队的持续改进和学习。随着时间推移，这些笔记变得更加有价值，成为团队智慧的集体体现。

通过掌握结构化笔记技术，开发团队可以建立强大的知识管理系统，显著提高项目的连续性、质量和效率。