# Context Engineer

> AI Agent 上下文工程专家 - Git 上下文、内存层级、会话状态追踪、@include指令处理、PII 保护和智能缓存策略

- Skill: `nihao555-hub/context-engineer` (Agent Skill)
- Install (CLI): `npx skillmds@latest add nihao555-hub/context-engineer`
- Raw SKILL.md: https://api.skillmd.com/api/skills/nihao555-hub/context-engineer/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: nihao555-hub (https://skillmd.com/u/nihao555-hub)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/nihao555-hub/context-engineer

---


# Context Engineer

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

## 目标

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

## 核心能力

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

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

```typescript
// 关键实现模式 - 并行执行 + 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 指令处理

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

```markdown
# 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 保护系统

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

```typescript
// ✅ 安全的日志
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. 智能缓存策略

多层缓存架构：

```typescript
// 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 文件**
   ```bash
   # 查找所有层级的 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 上下文增强方案

```typescript
// 扩展示例：添加 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）

## 输出格式

### 📊 现状评估

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

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

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

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

### 🏗️ 架构设计

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

### 📝 实现蓝图

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

### 🔍 测试计划

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

### ⚠️ 风险评估

| 风险项 | 可能性 | 影响程度 | 缓解措施 |
|-------|--------|----------|----------|
| 循环引用导致死循环 | 中 | 高 | 实现 visited set 检测 |
| 大文件拖慢系统 | 高 | 中 | 强制截断 + 流式读取 |
| PII 意外泄露 | 低 | 极高 | 双重审核 + 自动化测试 |
| 缓存不一致 | 中 | 中 | 版本号 + 哈希校验 |

## 交付物清单

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

---

# 🤖 AI IDE 开发指南

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

## AI IDE 开发前检查

### Git 环境验证
```yaml
必须检查:
  - git 命令行工具是否可用
  - 当前目录是否在 git 仓库中
  - git 用户配置是否存在

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

### 内存文件发现
```yaml
扫描路径:
  - /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. **优先级检查**
   ```typescript
   // ✅ 正确的优先级顺序
   const priority = {
     managed: 1,
     user: 2,
     project: 3,
     local: 4  // 最高优先级，最后应用
   }
   
   // ❌ 错误的顺序
   // 先应用 local 再应用 project = local 被覆盖
   ```

2. **PII 过滤验证**
   ```typescript
   // 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. **缓存策略优化**
   ```typescript
   // 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 完成后验证

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

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

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

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

### 自动化测试清单
AI IDE应该运行：
```bash
# 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 常见陷阱检测

### 🔴 高危问题（必须修复）
```typescript
// ❌ 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()
```

### 🟡 中等风险（建议优化）
```typescript
// ⚠️ 缓存 TTL 过长
memoize(fn, { maxAge: Infinity })  // 永不过期可能导致不一致
// AI IDE 应该：建议设置合理 TTL

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

### 🟢 低风险（可选改进）
```typescript
// 💡 可以优化的模式
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 集成实现示例

```typescript
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可以成长为能够独立设计和审查上下文工程系统的专家。