构建 AI 项目上下文 Skill

引言

在 AI 辅助编程实践中，一个常见的痛点是：每次开启新的对话，都需要重复描述项目结构、技术栈和编码规范。这种重复性解释不仅低效，且不同表述可能导致 AI 理解的不一致。AI 项目上下文技能正是为了解决这一问题而构建的。

问题的具体表现

考虑一个典型场景：你正在开发一个使用 Prisma、自定义认证系统和特定编码规范的 Next.js 项目。每次开始新的 AI 对话：

用户: "帮我添加一个新的 API 端点。"
AI: "好的！请问您使用什么框架？数据库如何配置？有现成的模式可以参考吗？"
用户: (叹气) "这是使用 App Router 的 Next.js 16 项目，ORM 用的是 Prisma，数据库是 PostgreSQL，我们采用服务层模式..."

这段对话不断重复。AI 项目上下文技能消除了这种开销。

方案

本项目遵循 Agent Skills 规范，通过定义一套轻量化的、可嵌入仓库的上下文文件体系，为 AI 助手提供结构化的项目理解。核心思路包括：

1. 项目结构扫描 —— 分析目录拓扑与依赖关系
2. 关键信息提取 —— 识别框架、模式与规范
3. 上下文持久化 —— 以 Markdown 形式存储于仓库中
4. 自动注入 —— AI 助手在对话中自动引用上下文文件

技术实现

核心组件

skills/ai-project-context/
├── SKILL.md              # Skill 定义：触发器、上下文层、安全策略
├── templates/
│   ├── AI_INDEX.template.md   # 项目索引模板
│   ├── ADR.template.md        # 架构决策记录模板
│   └── SSOT_SNIPPET.md        # 单一可信来源配置片段
└── scripts/
    └── analyze-project.ts     # 项目分析工具

上下文分层

系统将项目上下文划分为若干层次：

• 索引层：项目文件结构总览与关键路径说明
• 系统形态层：技术栈、框架版本、构建工具等
• 契约层：数据模型、API 接口、配置结构（以链接方式引用）
• 决策记录层：以 ADR 形式记录的架构决策及其理由

框架检测

const frameworkMap = {
  'next': 'Next.js',
  'react': 'React',
  'vue': 'Vue.js',
  '@angular/core': 'Angular',
  'svelte': 'Svelte',
  'express': 'Express',
  'fastify': 'Fastify',
  'nestjs': 'NestJS',
};
 
function detectFramework(deps: string[]): string[] {
  return deps
    .filter(dep => frameworkMap[dep])
    .map(dep => frameworkMap[dep]);
}

模式检测

该技能可以检测代码库中的常见模式：

interface PatternMatch {
  name: string;
  confidence: number;
  evidence: string[];
}
 
function detectPatterns(structure: DirectoryTree): PatternMatch[] {
  const patterns: PatternMatch[] = [];
 
  // 服务层模式
  if (hasDirectory(structure, 'services') &&
      hasDirectory(structure, 'controllers')) {
    patterns.push({
      name: 'Service Layer',
      confidence: 0.9,
      evidence: ['services/ 目录', 'controllers/ 目录']
    });
  }
 
  // 仓储模式
  if (hasDirectory(structure, 'repositories')) {
    patterns.push({
      name: 'Repository Pattern',
      confidence: 0.85,
      evidence: ['repositories/ 目录']
    });
  }
 
  return patterns;
}

安装方式

本工具以 Skill 文件夹形式使用，而非 npm 包。将 skills/ai-project-context/ 目录复制到 AI 客户端的 skills 目录即可。支持 Claude Code、Cursor 等遵循 agentskills.io 规范的客户端。

安装步骤

1. 复制技能目录：

cp -r skills/ai-project-context ~/.claude/skills/

2. 在项目中运行初始化：

# 该技能会自动在项目根目录创建 AI_INDEX.md

3. 根据具体需求自定义生成的上下文文件

使用示例

示例 1：新开发者入职

当新开发者询问项目情况时：

AI 读取 AI_INDEX.md 并立即理解：
- 技术栈：Next.js 16、Prisma、PostgreSQL
- 架构：App Router、服务层
- 关键目录：src/app、src/lib、src/components
- 规范：函数式组件、TypeScript 严格模式

示例 2：功能实现

请求新功能时：

用户: "添加一个用户资料页面"

有上下文的 AI：
- 知道路由约定 (src/app/[locale]/profile/page.tsx)
- 使用现有 UI 组件 (src/components/ui/)
- 遵循数据获取模式 (服务端组件 + Prisma)
- 应用正确的样式方法 (Tailwind + CSS 变量)

效果

使用该上下文体系后，AI 助手的辅助效果显著提升：

主要收益

• 聚焦度提高 —— 无需重复解释项目背景
• 一致性增强 —— 跨对话共享同一上下文
• 效率改善 —— 更快进入实际编码任务
• 错误减少 —— AI 自动遵循既有模式

后续方向

• Git 历史分析 —— 理解近期变更及其理由
• 自定义上下文模板 —— 针对项目类型定制（电商、SaaS 等）
• 多仓库支持 —— monorepo 结构的上下文管理
• 实时更新 —— 文件变更时自动刷新上下文

参考

• GitHub 仓库(opens in a new tab)
• Agent Skills 规范(opens in a new tab)
• 架构决策记录(opens in a new tab)