Context Engineer

Context Engineer

使用此技能当你需要设计上下文工程系统、管理多层级内存文件、或实现智能缓存策略。

目标

产出完整的上下文工程方案，包括 Git 上下文捕获、内存文件层级、@include 指令处理、PII 过滤和缓存策略。

核心能力

1. Git 上下文捕获 (src/context.ts)

Claude Code的Git 上下文系统设计原则：

// 关键实现模式 - 并行执行 + Memoization 缓存
export const getGitStatus = memoize(async (): Promise<string | null> => {
  const startTime = Date.now()
  
  // 并行获取所有 Git 信息（避免串行延迟）
  const [branch, mainBranch, status, log, userName] = await Promise.all([
    getCurrentBranch(),        // git rev-parse --abbrev-ref HEAD
    getMainBranch(),           // 检测 main/master/develop
    getGitStatus(),            // git status --porcelain
    getRecentCommits(),        // git log --oneline -10
    getGitUserName()           // git config user.name
  ])
  
  logForDiagnosticsNoPII('info', 'git_status_fetched', {
    duration_ms: Date.now() - startTime,
    branch_length: branch?.length,
    is_dirty: !!status?.trim()
  })
  
  return [
    `Git branch: ${branch}`,
    `Main branch: ${mainBranch}`,
    status ? `Status:\n${truncate(status, 2000)}` : 'Working tree clean',
    `Recent commits:\n${log}`,
    ...(userName ? [`Git user: ${userName}`] : [])
  ].join('\n\n')
}, { maxAge: Infinity })  // 进程生命周期内缓存

关键设计决策:

• Memoization: 使用 lodash-es/memoize，maxAge: Infinity（进程内单例）
• 并行执行: Promise.all同时发起5个git命令，减少~80%等待时间
• 截断保护: status限制2000字符，防止超大仓库拖慢系统
• 错误隔离: try-catch包裹，失败时返回null而非抛出异常
• PII 保护: 记录耗时和脏状态，但不泄露具体文件路径

2. 内存文件层级系统 (src/utils/claudemd.ts)

四层内存文件架构（优先级从低到高）：

1. Managed Memory (/etc/claude-code/CLAUDE.md)
   - 系统管理员设置的全局规则
   - 适用于所有用户的所有项目
   - 通常包含：公司政策、安全规范、合规要求

2. User Memory (~/.claude/CLAUDE.md)
   - 用户个人全局偏好
   - 跨项目生效的个人习惯
   - 例如：代码风格偏好、常用命令别名

3. Project Memory (CLAUDE.md, .claude/CLAUDE.md, .claude/rules/*.md)
   - 项目特定的开发规范
   - 团队协作约定
   - 架构决策记录 (ADRs)

4. Local Memory (CLAUDE.local.md)
   - 私有项目配置
   - 不应提交到版本控制的敏感信息
   - 临时实验性设置

文件加载顺序：后者覆盖前者，local 优先级最高。

3. @include 指令处理

内存文件支持模块化引用：

# CLAUDE.md 示例

我们使用 TypeScript 严格模式。

@include ./rules/typescript.md
@include ./rules/testing.md
@include ~/.claude/snippets/common.md

路径解析规则:

• @path - 相对当前文件所在目录
• @./path - 显式相对路径
• @~/path - 相对于用户家目录
• @/absolute/path - 绝对路径

防循环引用机制：使用 visited set 检测循环。

4. PII 保护系统

严格区分"可日志信息"和"敏感信息"：

// ✅ 安全的日志
logForDiagnosticsNoPII('info', 'file_read', {
  extension: 'ts',           // 文件扩展名 - 安全
  line_count: 150,           // 行数 - 安全
  has_exports: true          // 是否有导出 - 安全
})

// ❌ 危险的日志（禁止！）
logForDiagnosticsNoPII('info', 'file_read', {
  file_path: '/Users/john.doe/projects/secret-app/src/auth.ts',  // PII!
  content_preview: 'const API_KEY = "sk-..."',                   // PII!
  git_user: 'john.doe@company.com'                               // PII!
})

PII 分类:

• 个人信息: 用户名、邮箱、家目录路径
• 凭证信息: API keys、密码、token
• 业务敏感: 未公开的产品名称、内部项目代号
• 基础设施: 内网 IP、服务器主机名、数据库连接字符串

5. 智能缓存策略

多层缓存架构：

// L1 Cache: 内存缓存（最快，进程内有效）
const gitStatusCache = memoize(async () => {
  return fetchGitStatus()
}, { maxAge: 5 * 60 * 1000 })  // 5 分钟 TTL

// L2 Cache: 磁盘缓存（较慢，跨进程持久）
async function getCachedContext(sessionId: string) {
  const cachePath = join(getCacheDir(), sessionId, 'context.json')
  try {
    const cached = await readFile(cachePath)
    const parsed = JSON.parse(cached)
    
    if (Date.now() - parsed.timestamp < CACHE_TTL) {
      return parsed.data
    }
  } catch {}
  
  // Cache miss - 重新计算并写入
  const fresh = await computeFreshContext()
  await writeFile(cachePath, JSON.stringify({
    timestamp: Date.now(),
    data: fresh
  }))
  return fresh
}

工作流程

第一步：审计现有上下文系统 (15 分钟)

1. 检查 CLAUDE.md 文件

   # 查找所有层级的 CLAUDE.md
   find . -name "CLAUDE.md" -o -name "CLAUDE.local.md"
   find ~/.claude -name "*.md" 2>/dev/null
   cat /etc/claude-code/CLAUDE.md 2>/dev/null || echo "No managed config"
   

2. 分析 Git 上下文质量

   • 是否捕获了分支信息？
   • 是否检测了工作树变更？
   • 是否包含了最近提交历史？
   • 是否有 Git 用户信息？
   • 错误处理是否健壮？

3. 审查内存文件结构

   • 文件层级是否清晰（managed/user/project/local）
   • 是否存在@include 循环引用风险
   • 敏感信息是否正确隔离在 local 层
   • 项目规则是否模块化（.claude/rules/）

第二步：设计上下文架构 (20 分钟)

基于 Claude Code最佳实践，设计：

1. Git 上下文增强方案

// 扩展示例：添加 Git 远程仓库信息
export const getGitRemoteInfo = memoize(async () => {
  const remotes = await exec('git remote -v')
  const currentRemote = extractCurrentRemote(
    await exec('git config --get remote.origin.url')
  )
  
  return {
    remotes: parseRemotes(remotes),
    currentRemote,
    hostingProvider: detectHostingProvider(currentRemote)
  }
})

2. 内存文件模板

创建标准化的项目内存文件结构。

3. 缓存策略设计

定义缓存键生成规则、TTL 配置、失效条件。

第三步：实现与验证 (25 分钟)

实现检查清单

• Git 上下文模块

  • 分支信息获取（含 detached HEAD 处理）
  • 主分支自动检测（main/master/develop）
  • 工作状态检查（带 truncation 保护）
  • 提交历史格式化（--oneline -10）
  • Git 用户信息读取
  • 错误处理和降级策略

• 内存文件加载器

  • 四层内存文件发现逻辑
  • 向上遍历到 git root
  • .claude/rules/目录支持
  • @include指令解析
  • 循环引用检测
  • 路径规范化（~, ./, 绝对路径）

• PII 过滤器

  • 用户名/邮箱脱敏
  • 家目录路径替换
  • API keys 检测
  • 日志内容审核
  • 诊断信息安全检查

• 缓存管理器

  • 内存缓存（memoize）
  • 磁盘缓存（JSONL 文件）
  • TTL 失效逻辑
  • 手动失效接口
  • 缓存命中率统计

规则

• ✅ 始终假设文件系统是不可靠的（处理不存在的文件、权限错误）
• ✅ 对所有外部输入保持警惕（路径遍历攻击、恶意@include）
• ✅ 优先考虑渐进增强（没有 Git 也能正常工作）
• ✅ 记录所有缓存命中/失事件用于性能分析
• ❌ 不要在日志中输出完整文件路径（尤其是包含用户名的）
• ❌ 不要无限递归@include（必须有循环检测）
• ❌ 不要假设 Git 仓库一定存在（处理非 Git 项目）
• ❌ 不要阻塞主线程进行文件 IO（始终使用异步 API）

输出格式

📊 现状评估

## Git 上下文成熟度
评分：X/10
优势：...
不足：...

## 内存文件完整性
评分：X/10
已覆盖层级：managed □ user □ project □ local □
缺失内容：...

## PII 保护有效性
评分：X/10
已保护措施：...
潜在风险：...

## 缓存策略效率
评分：X/10
缓存命中率：X%
平均响应时间：X ms
改进空间：...

🏗️ 架构设计

使用 Mermaid 图表展示层次结构。

📝 实现蓝图

提供四个核心模块的完整 TypeScript 实现代码。

🔍 测试计划

单元测试、集成测试、性能测试的详细计划。

⚠️ 风险评估

交付物清单

最终报告应包含：

• 上下文系统现状评估（四个维度打分）
• 架构设计图（Mermaid 流程图）
• 四个核心模块的完整实现代码
• 测试计划和测试用例
• 风险评估和缓解措施
• 性能基准和优化建议
• 迁移指南（如果重构现有系统）

🤖 AI IDE 开发指南

本部分指导 AI IDE 按照 Claude Code的最佳实践开发上下文工程系统。

AI IDE 开发前检查

Git 环境验证

必须检查:
  - git 命令行工具是否可用
  - 当前目录是否在 git 仓库中
  - git 用户配置是否存在

降级策略:
  - 非 git 目录 → 返回 null 而非报错
  - git 命令失败 → 静默降级为空上下文
  - 权限不足 → 记录诊断日志但不阻断

内存文件发现

扫描路径:
  - /etc/claude-code/CLAUDE.md (managed)
  - ~/.claude/CLAUDE.md (user)
  - {cwd}/**/CLAUDE.md (project, 向上遍历到 git root)
  - {cwd}/**/.claude/CLAUDE.md (project)
  - {cwd}/**/.claude/rules/*.md (project rules)
  - {cwd}/CLAUDE.local.md (local)

警告信号:
  - @include 循环引用风险
  - 文件过大 (>1MB)
  - 敏感信息可能泄露

AI IDE 开发中指导

实时上下文质量监控

当加载内存文件时，AI IDE应该：

1. 优先级检查

   // ✅ 正确的优先级顺序
   const priority = {
     managed: 1,
     user: 2,
     project: 3,
     local: 4  // 最高优先级，最后应用
   }
   
   // ❌ 错误的顺序
   // 先应用 local 再应用 project = local 被覆盖
   

2. PII 过滤验证

   // AI IDE 应该自动检测并警告
   const piiPatterns = {
     email: /[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}/g,
     homePath: /\/Users\/[^/]+\//g,
     apiKey: /sk-[a-zA-Z0-9]{32,}/g
   }
   
   // 如果发现 PII，建议移动到 CLAUDE.local.md
   

3. 缓存策略优化

   // AI IDE 应该推荐合适的 TTL
   const cacheStrategy = {
     gitStatus: 5 * 60 * 1000,      // 5 分钟
     memoryFiles: 60 * 60 * 1000,   // 1 小时
     sessionContext: Infinity       // 会话期间
   }
   

@include指令处理

AI IDE应该提供：

• 循环引用检测: 使用 visited set跟踪已处理文件
• 路径解析验证: 确保@~/、@./、@/路径正确解析
• 错误恢复: 单个@include失败不影响其他内容加载

AI IDE 完成后验证

上下文健康度评分卡

Git 上下文 (0-10分):
  - 分支信息完整性
  - 工作状态准确性
  - 提交历史可读性
  - 错误处理健壮性

内存文件 (0-10分):
  - 四层覆盖率
  - 模块化程度 (@include使用)
  - PII 隔离正确性
  - 循环引用零容忍

缓存系统 (0-10分):
  - 命中率 > 80%
  - TTL 配置合理性
  - 失效机制可靠性
  - 内存占用可控

总分评级:
  - 90-100: Excellent (生产就绪)
  - 75-89: Good (少量优化)
  - 60-74: Fair (需要改进)
  - <60: Poor (建议重构)

自动化测试清单

AI IDE应该运行：

# 1. Git 上下文测试
test('handles non-git directory', () => {...})
test('detects main branch correctly', () => {...})

# 2. 内存文件测试
test('respects priority order', () => {...})
test('detects circular includes', () => {...})

# 3. PII 过滤测试
test('redacts emails from logs', () => {...})
test('hides home paths', () => {...})

# 4. 缓存测试
test('cache hits return instantly', () => {...})
test('TTL expiration works', () => {...})

AI IDE 常见陷阱检测

🔴 高危问题（必须修复）

// ❌ PII 泄露到日志
logForDiagnosticsNoPII('info', 'debug', {
  filePath: '/Users/john.doe/...'  // 包含用户名!
})
// AI IDE 应该：立即警告 + 建议脱敏

// ❌ @include 循环引用
// fileA.md: @include fileB.md
// fileB.md: @include fileA.md
// AI IDE 应该：检测死循环风险 + 阻断加载

// ❌ 同步阻塞 IO
const content = readFileSync('CLAUDE.md')  // 阻塞主线程!
// AI IDE 应该：建议改为 await readFile()

🟡 中等风险（建议优化）

// ⚠️ 缓存 TTL 过长
memoize(fn, { maxAge: Infinity })  // 永不过期可能导致不一致
// AI IDE 应该：建议设置合理 TTL

// ⚠️ 大文件未截断
const status = execSync('git status')  // 可能返回超大输出
// AI IDE 应该：建议添加 truncate 保护

🟢 低风险（可选改进）

// 💡 可以优化的模式
const context = await loadFromDisk()
if (!context) { await loadFresh() }
// AI IDE 可以建议：使用缓存包装器自动处理

AI IDE 代码审查检查清单

在 PR/MR阶段，AI IDE应该自动检查：

上下文完整性

• Git 上下文包含所有必要字段
• 内存文件按正确优先级加载
• @include指令无循环引用
• PII 已正确过滤

性能影响

• 使用了 memoization 缓存
• 异步 IO 不阻塞主线程
• 大文件有截断保护
• 缓存命中率可监控

安全合规

• 日志不含 PII
• 敏感数据隔离在 local层
• 路径遍历攻击已防护
• 错误信息不泄露内部结构

可维护性

• 函数长度 < 50行
• 单一职责原则
• 有单元测试覆盖
• 文档更新已完成

AI IDE 集成实现示例

interface ContextRule {
  id: string
  description: string
  severity: 'error' | 'warning' | 'info'
  check: (context: ContextData) => Violation[]
  fix?: (violation: Violation) => Fix
}

const rules: ContextRule[] = [
  {
    id: 'CTX-001',
    description: 'PII must not appear in logs',
    severity: 'error',
    check: (context) => {
      const piiDetected = detectPII(context.metadata)
      return piiDetected.map(pii => ({
        message: `PII detected: ${pii.type}`,
        location: pii.location
      }))
    },
    fix: (violation) => ({
      type: 'redact',
      pattern: violation.piiType
    })
  },
  {
    id: 'CTX-002',
    description: 'Circular @include detection',
    severity: 'error',
    check: (context) => {
      const cycles = detectCircularIncludes(context.includes)
      return cycles.map(cycle => ({
        message: `Circular include detected: ${cycle.join(' -> ')}`,
        location: cycle[0]
      }))
    }
  }
  // ... 更多规则
]

AI IDE 学习路径

为了让 AI IDE更好地理解上下文工程规范：

1. 第一阶段: 学习 Git 上下文捕获原理
2. 第二阶段: 理解四层内存文件架构
3. 第三阶段: 掌握@include指令处理和循环检测
4. 第四阶段: 实现 PII 自动识别和过滤
5. 第五阶段: 提供智能缓存策略推荐

通过学习路径，AI IDE可以成长为能够独立设计和审查上下文工程系统的专家。