Personal AI Engineering Context 实践教程

本教程用于在任意本地代码仓库中建立一套仅服务个人开发者与 AI Coding 的长期工程上下文。它解决的是 AI 长会话丢失早期信息、重复实现已有能力，以及开发者难以持续追溯需求背景和技术决策的问题。

本体系不是团队工程文档，不替代源码、测试、README、接口文档或正式架构文档。

快速安装

本目录可以作为独立 Git 仓库发布到 GitHub。安装端不需要运行脚本：Codex 或其他 Coding Agent 读取 INSTALL.md 后，会在目标仓库完成预检、Repository Discovery、上下文创建、Git 忽略验证和 Fresh Session Recovery Test。

推荐用法：

将本目录提交到自己的 GitHub 仓库。
在目标项目中打开 Coding Agent。
将 prompts/INSTALL_WITH_AGENT.md 中的提示词交给 Agent，并替换安装包地址与目标仓库路径。
Agent 默认在 Repository Discovery 后暂停，等待确认，再写入项目专属上下文。

OR直接告诉Agent:

请读取并严格执行 <GitHub仓库或本地路径>/INSTALL.md，为目标仓库 <目标项目绝对路径> 安装 Personal AI Engineering Context。

本安装包采用“协议 + 模板”，而不是自动化脚本。原因是 PROJECT、CODEMAP、测试风险和生成规则必须从每个目标仓库重新调查，不能通过机械复制可靠生成。

仓库结构：

personal-ai-engineering-context-tutorial/
├── README.md
├── INSTALL.md
├── prompts/
│   └── INSTALL_WITH_AGENT.md
└── templates/
    ├── AGENTS.md
    ├── PROJECT.md
    ├── CODEMAP.md
    ├── CURRENT.md
    ├── REQ.md
    └── ADR.md

1. 目标与边界

建立后，新的 AI 会话应能快速回答：

这个项目是什么，如何启动。
真实架构和请求链路是什么。
重要公共能力和业务入口在哪里。
当前正在做什么。
某项需求为什么做、已经实现了什么。
重要技术方案为什么这样选择。
修改业务前需要调查哪些源码、状态、数据和测试风险。

默认边界：

所有上下文文件只供当前开发者和 AI Coding 使用。
所有上下文文件均受 Git 忽略，不提交到团队仓库。
不修改团队共享工程文档。
建立上下文时不修改业务代码。
源码始终比上下文文档更权威。
所有 Personal AI Engineering Context Markdown 使用中文；代码标识符、路径、API 名称和必要原文保持原样。
不在上下文中记录凭证、Token、私有地址、生产数据或团队私有流程。

2. 目录结构

在目标项目根目录建立：

AGENTS.md
.ai-context/
├── context/
│   ├── PROJECT.md
│   └── CODEMAP.md
├── CURRENT.md
├── requirements/
└── decisions/

各文件职责：

文件	回答的问题	内容稳定性
`AGENTS.md`	AI 应该如何工作	稳定工作规范
`PROJECT.md`	这个项目是什么	稳定工程事实
`CODEMAP.md`	重要能力在哪里	重要导航地图
`CURRENT.md`	当前正在做什么	短期当前状态
`requirements/REQ-xxx.md`	为什么做这个需求	需求级可追溯记录
`decisions/ADR-xxx.md`	为什么采用这个方案	重要技术决策记录

3. 第零阶段：确认项目规则

开始前确认：

项目根目录的准确路径。
是否已有 AGENTS.md 或其他 AI 指令文件。
应使用仓库本地 .git/info/exclude，还是允许修改 .gitignore。
上下文使用语言。本教程默认中文。
是否存在不能读取的目录、配置或敏感数据。
是否允许创建项目级 Skill。Skill 不是基础体系的必需条件。

如果仓库已有团队维护的 AGENTS.md，不要直接覆盖。应先判断它是否属于团队文件；必要时选择团队允许的个人指令机制，或停止并与用户确认。

4. 第一阶段：Repository Discovery

第一阶段只读取和分析，不创建文件、不修改代码、不运行构建或测试。

4.1 调查范围

根据项目实际结构调查：

项目说明、依赖清单、启动入口和构建文件。
API、controller、service、logic、DAO、model 或项目实际采用的层次。
数据库、缓存、消息队列、文件存储和事务边界。
认证、授权、加密、限流、锁、幂等和并发能力。
重要 utility、共享基础设施和外部服务 wrapper。
核心业务域、状态机、事件和跨领域流程。
配置加载、动态配置和环境差异。
生成代码标记、生成来源和安全修改边界。
单元测试、集成测试、测试 bootstrap、真实外部依赖和副作用。
已有工程文档，但不能仅凭文档推断源码结构。

4.2 调查原则

不根据框架经验猜测真实架构。
从入口追踪实际调用链，并搜索调用方和引用。
识别“文档约定”和“当前代码事实”的差异。
CODEMAP 只收录重要导航，不枚举所有函数、DAO、API 或 CRUD。
不复制具体密钥、连接地址或生产配置值。
无法确认的内容进入 Unknowns，不用推测补全。

4.3 Repository Discovery 提示词

将 <PROJECT_PATH> 替换为目标仓库绝对路径：

你现在负责为本地仓库 <PROJECT_PATH> 建立 Personal AI Engineering Context。

当前只执行 Repository Discovery，严格只读：
1. 不创建或修改任何文件。
2. 不修改业务代码、团队文档或 Git。
3. 不运行测试、构建、生成器或迁移。
4. 调查项目定位、启动方式、真实架构、请求链路、数据存储、缓存与并发、公共能力、核心业务域、生成代码、配置、外部集成、测试风险和已有文档。
5. 不根据框架经验猜测；结论必须来自当前仓库证据。
6. 源码与文档不一致时，以源码为准并指出差异。
7. 不输出敏感配置值。

请输出 Repository Discovery Report，包含：
1. Project Overview
2. Application Startup
3. Architecture Layers
4. Request Lifecycle
5. Database Architecture
6. Cache and Concurrency
7. Shared Utilities
8. Business Domains
9. Generated Code
10. Configuration
11. External Integrations
12. Testing
13. Existing Documentation
14. Important Engineering Conventions
15. Unknowns

完成后停止，等待确认。

5. 第二阶段：建立基础上下文

只有确认 Repository Discovery 基本正确后才创建文件。

5.1 Git 忽略规则

个人上下文默认优先加入仓库本地的 .git/info/exclude，这样不会修改团队共享的 .gitignore。先用以下命令找到正确文件：

git rev-parse --git-path info/exclude

在该文件中加入：

AGENTS.md
.ai-context/

只有用户明确允许修改共享忽略规则时，才改项目 .gitignore。如果创建项目级 Skill，并且放在个人专用目录，例如 .agents/skills/，只忽略本次创建的具体 Skill 路径；不要在不了解团队约定时忽略整个团队正在使用的 .agents/ 目录。

如果 AGENTS.md 已被 Git 跟踪，忽略规则不会使它变成本地文件。安装器必须停止并由用户选择：保留团队 AGENTS、明确批准合并团队规则，或改用当前 Agent 支持的个人指令入口。不得覆盖已跟踪的团队文件。

创建后使用以下命令验证：

git check-ignore -v AGENTS.md .ai-context/CURRENT.md
git status --short --untracked-files=all -- AGENTS.md .ai-context

第一条应显示匹配的忽略规则；第二条应没有输出。

5.2 AGENTS.md

AGENTS 只规定 AI 如何工作，不记录具体项目知识。建议覆盖：

修改前读取 PROJECT、CODEMAP、CURRENT 和相关 REQ/ADR。
从 Plan 进入实现时重新读取上下文，不只依赖聊天摘要。
新建公共能力前搜索已有实现和引用。
源码优先，CODEMAP 只用于导航。
修改前分析入口、调用方、状态、持久化、配置、外部集成、生成文件和测试。
运行测试前检查初始化和副作用。
修改后检查 diff、执行最窄安全验证并同步上下文。
上下文统一使用中文且不记录敏感信息。
只在出现漂移信号时建议 Context Drift Review。

不要把技术栈、目录地图或当前任务写入 AGENTS。

5.3 PROJECT.md

PROJECT 只记录稳定工程事实：

项目类型和核心业务域。
运行时、技术栈和启动方式。
真实架构层次及例外情况。
请求、安全和身份边界。
数据库、缓存、消息和跨存储一致性边界。
配置来源，不记录具体敏感值。
外部集成。
测试类型与稳定风险。
生成代码方式和修改边界。

不要记录当前任务、聊天历史、临时状态或技术债清单。

5.4 CODEMAP.md

CODEMAP 用于快速找到重要能力：

启动与路由入口。
API 和请求处理边界。
身份、安全、锁、限流、幂等、加密。
共享基础设施和高复用 utility。
核心业务入口和状态机。
数据、存储和外部服务 wrapper。
生成代码边界和测试 bootstrap。

遵循：

CODEMAP -> 找到候选位置 -> 查看源码 -> 搜索引用

不要加入行号，不列出所有函数、DAO、API 或普通 CRUD。

5.5 CURRENT.md

CURRENT 始终保持短，只包含：

# 当前工作

## 当前状态

- 当前需求或等待状态。

## 已完成

- 本需求已经完成的关键结果。

## 下一步

- 紧接的一个或少量具体动作。

## 阻塞项

无，或记录真实阻塞。

不要复制 PROJECT、CODEMAP 或完整工作日志。

5.6 基础上下文创建提示词

Repository Discovery 已确认。现在建立 Personal AI Engineering Context 基础体系。

要求：
1. 创建 AGENTS.md、.ai-context/context/PROJECT.md、.ai-context/context/CODEMAP.md、.ai-context/CURRENT.md、.ai-context/requirements/ 和 .ai-context/decisions/。
2. AGENTS 只写 AI 工作规范；PROJECT 只写稳定工程事实；CODEMAP 只写重要能力导航；CURRENT 保持简短。
3. 所有上下文 Markdown 使用中文，保留代码标识符、路径和 API 名称。
4. 不记录凭证、Token、私有地址、生产数据或团队私有流程。
5. 默认在仓库本地 .git/info/exclude 中加入必要规则；只有用户明确允许时才修改 .gitignore。验证所有上下文路径受 Git 忽略。
6. 不修改业务代码或团队共享文档。
7. 不运行项目测试、构建或生成器，不提交 Git。
8. 结论必须来自已确认的 Repository Discovery；不确定内容明确保留为未知项。

6. 第三阶段：Fresh Session Recovery Test

基础文件创建后，模拟一个完全新的 AI 会话。测试时只能读取：

AGENTS.md
.ai-context/context/PROJECT.md
.ai-context/context/CODEMAP.md
.ai-context/CURRENT.md

不得使用先前聊天、Discovery Report、源码、README、Git 历史或其他文档作为补充。

验证能否恢复：

项目是什么。
真实架构是什么。
请求通常如何流转。
数据与并发边界是什么。
重要公共能力在哪里。
修改核心业务时应继续调查什么。
哪些生成和测试操作有风险。
当前正在做什么。

Recovery Test 提示词

执行 Fresh Session Recovery Test，模拟完全新的 AI session。

严格限制只读取：
- AGENTS.md
- .ai-context/context/PROJECT.md
- .ai-context/context/CODEMAP.md
- .ai-context/CURRENT.md

不得读取其他源码、README、构建文件、配置、Git 历史或文档；不得使用当前聊天中的 Discovery Report；不得创建或修改文件；不运行测试、构建或 Git 操作。

输出：
1. Project Understanding
2. Architecture Understanding
3. Request Lifecycle Understanding
4. Data and Concurrency Understanding
5. Existing Capabilities Located
6. Business Change Investigation Workflow
7. Generated Code Safety
8. Testing Safety
9. Current Work Recovery
10. Missing or Ambiguous Context
11. Recovery Verdict

如果发现缺失，只提出最小且精确的修订建议，不修改文件。

通过标准不是“能够直接写代码”，而是“能够正确理解项目，并知道下一步应该去哪里核实源码”。

7. 实际需求生命周期

7.1 Plan 模式

收到实际业务需求后，先在 Plan 模式只读调查：

读取四个基础上下文文件。
查看相关 REQ 和 ADR。
将 CODEMAP 作为导航，再检查源码和引用。
还原现有行为、调用链、数据写入和状态变化。
搜索可复用能力。
确认生成文件和测试风险。
输出需求理解、影响范围、方案、验证计划和 REQ 草稿。

Plan 模式不创建 REQ、不更新 CURRENT、不修改业务代码，也不运行有副作用的命令。完成后使用 Plan 原生控件修订或批准。

7.2 Default 模式实现

计划获批并进入可写模式后：

重新读取基础上下文、相关 REQ/ADR 和目标源码。
确认计划与用户最新指令没有冲突。
先创建对应 REQ，再修改业务代码。
更新 CURRENT 为当前活跃需求。
只有存在重要技术取舍时才创建 ADR。
实现批准范围并执行最窄安全验证。
检查完整 diff。
更新 REQ 的实现、测试和结果。
更新 CURRENT 的完成状态、下一步和阻塞项。
根据稳定事实和重要导航变化决定是否更新 PROJECT/CODEMAP。

8. REQ：需求追溯

REQ 文件建议命名为：

.ai-context/requirements/REQ-001.md
.ai-context/requirements/REQ-002.md

模板：

# REQ-xxx：需求标题

## 背景

为什么提出该需求，解决什么问题。

## 目标

期望达到的业务结果。

## 需求

- 可观察行为和验收标准。
- 约束与非目标。

## 现有行为

实现前已确认的系统行为和证据。

## 实现

实际采用的方案、复用能力和变更范围。未实现时标记为待处理。

## 测试

实际运行的验证、结果，以及因环境或风险未运行的测试。

## 结果

最终交付结果、剩余限制和后续事项。

REQ 记录“为什么做”和“实际交付了什么”，不是逐步操作日志，也不复制聊天历史。

9. ADR：重要技术决策

只有满足以下条件时才创建 ADR：

存在两个或以上真实可行方案。
选择会影响后续架构、数据、安全、兼容性或运维方式。
未来开发者或 AI 有必要理解当时为什么这样选择。

普通命名、局部重构、常规 CRUD 或显而易见的实现细节通常不需要 ADR。

模板：

# ADR-xxx：决策标题

## 背景

需要做出什么选择，受哪些条件限制。

## 决策

采用的方案及核心理由。

## 备选方案

- 方案 A：优点、缺点和未采用原因。
- 方案 B：优点、缺点和未采用原因。

## 后果

正面影响、负面影响、风险和后续约束。

10. Context Drift Review

项目持续演进后，PROJECT 和 CODEMAP 不可能自动保持完整。任务收尾时检查漂移信号，但不要每次小改动都执行全量审查。

建议检查的信号：

重大业务域或跨领域流程新增、删除或大幅重构。
重要共享能力、基础设施、安全、并发、存储或外部服务入口新增、移动、重命名或删除。
架构、数据、缓存、配置、外部集成、测试、启动或生成规则的稳定事实变化。
PROJECT/CODEMAP 被发现与源码不一致。
CODEMAP 多次无法定位重要已有能力。
完成多个相关的重要需求或一个明确里程碑。

通常不需要单独检查：

孤立 CRUD。
私有 helper。
仅格式调整。
常规测试补充。
尚未形成稳定事实变化的未完成工作。

Drift Review 提示词

执行 Personal AI Engineering Context Drift Review。

要求：
1. 先读取 AGENTS、PROJECT、CODEMAP、CURRENT 及相关近期 REQ/ADR。
2. 以当前源码、配置结构、生成标记和测试为权威证据。
3. 检查 PROJECT 的稳定工程事实、CODEMAP 的重要能力导航、CURRENT 的当前状态、REQ 的实现/测试/结果和 ADR 的有效性。
4. 将发现分类为错误、过期或缺失，并给出源码证据。
5. 不把 PROJECT 变成日志，不把 CODEMAP 变成符号清单，不把 CURRENT 变成历史流水。
6. Plan 模式严格只读，只提出最小修改建议。
7. 获得批准并进入可写模式后，只修改已证实漂移的上下文 Markdown。
8. 所有更新使用中文，不修改业务代码或团队文档，不运行项目测试、构建、生成器或迁移。
9. 验证上下文路径仍受 Git 忽略。

11. 是否需要项目级 Skill

基础上下文体系不依赖 Skill。稳定使用一段时间后，可以为单个项目创建两个可选 Skill：

需求管理 Skill：连接 Plan 模式分析、REQ 草稿、批准后实现和文档收尾。
Context Drift Review Skill：按信号审查上下文与源码偏差。

Skill 必须项目专用，因为需要包含项目路径、上下文入口、领域调查重点、生成规则和测试风险。不要把一个项目的 Skill 原样复制给另一个项目。

创建新项目 Skill 时：

使用官方 skill-creator 流程初始化和验证。
项目级 Skill 放入该项目允许的个人 Skill 目录，并确保受 Git 忽略。
Plan 模式严格只读。
Skill 不覆盖 Plan 原生执行或修订控件。
开始实现时重新读取项目上下文。
不为文档工作创建脚本、自动化工具、references 或 assets，除非确有独立必要。

12. 新项目启动顺序

推荐固定顺序：

确认边界
  -> Repository Discovery（只读）
  -> 用户确认 Discovery
  -> 创建基础上下文并验证 Git 忽略
  -> Fresh Session Recovery Test
  -> 修正最小缺失
  -> 开始第一个实际需求
  -> REQ/ADR 生命周期
  -> 按信号执行 Context Drift Review

不要跳过 Discovery 后直接复制其他项目的 PROJECT 或 CODEMAP。可以复用结构和流程，但每个工程事实都必须重新从目标仓库确认。

13. 日常使用检查表

开始需求前

使用 Plan 模式。
读取四个基础上下文文件。
阅读相关 REQ/ADR。
从 CODEMAP 定位，再查看源码并搜索引用。
找到已有公共能力和影响范围。
确认生成文件与测试风险。
形成 REQ 草稿、实现计划和验证计划。

批准实现后

重新读取上下文和目标源码。
创建 REQ 并更新 CURRENT。
必要时创建 ADR。
修改范围与批准计划一致。
执行最窄安全验证。
检查完整 diff。

任务完成后

更新 REQ 的实现、测试和结果。
更新 CURRENT 的完成状态、下一步和阻塞项。
仅在稳定事实变化时更新 PROJECT。
仅在重要能力导航变化时更新 CODEMAP。
评估是否出现漂移检查信号。
确认上下文仍受 Git 忽略。

14. 常见错误

把聊天历史当作长期知识库。
未搜索已有 utility 就创建重复 helper。
按框架经验填写架构，而不是追踪真实调用关系。
把 CODEMAP 写成所有文件和函数的清单。
把 PROJECT 写成任务日志或技术债列表。
把 CURRENT 写成长期历史记录。
每个小选择都创建 ADR。
Plan 模式中提前创建 REQ 或修改代码。
从 Plan 进入实现时只依赖摘要，不重新读取上下文。
直接修改生成产物而不调查生成来源。
默认运行宽泛测试命令，忽略真实数据库、缓存和外部服务副作用。
将上下文提交 Git 或混入团队文档。
将另一个项目的工程事实和 Skill 原样复制过来。

15. 最终验收标准

一套上下文体系只有同时满足以下条件才算建立完成：

Name		Name	Last commit message	Last commit date
prompts		prompts
templates		templates
INSTALL.md		INSTALL.md
README.md		README.md

Latest commit

History

Folders and files

Repository files navigation