没有历史对话，Agent 如何恢复项目？

本篇文章想要解答什么问题？我想要记录的是一个标准的 vibe-coding 项目包含哪些东西。最终实现的效果是让没有历史对话的新会话，仅通过仓库就能理解项目、恢复状态并执行正确流程。

我们可以把 LLM 比作近似无状态函数。

如果我们想要面向 Agent 编程，那仓库不仅保存代码，还要保存 Agent 工作所需的有效事实、流程入口、机器状态和长期经验。

Agent 工作环境包含哪几层能力

项目骨架

project/
├── .agents/               # Agent 工具的本地配置：技能、流程钩子、外部连接
│   ├── skills/            # 技能：可重复、按需触发的做法（语义相关、需 AI 处理）
│   ├── hooks/             # 任务流程：某类任务按什么步骤完成（hooks、脚本、模板）
│   └── mcp.json           # 外部连接：访问 Issue、构建、数据库和内部文档的受控入口
├── docs/
│   └── adr/               # 经验：跨需求仍然有效的决策（ADR、decisions.md）
├── rules/                 # 规则：底线和稳定约束，与 AGENTS.md 共同定义角色与边界
├── specs/                 # 事实：当前仍然有效的契约和项目知识（架构文档、接口定义）
├── tasks/                 # 过程：任务分解与进行中事项
├── workflow/              # 过程：本轮需求如何讨论和收敛（方案记录）
├── workflow-state.json    # 状态：当前阶段和允许动作（机器可读）
└── AGENTS.md              # 角色：Agent 应怎样工作、不能越过什么边界（每次进入必读）

根据项目情况进行删减，这只是全量的文件夹。能力分发（一组规则、流程和资源如何安装复用）不落目录，由 Plugin、工具包承载。

AGENTS.md

AGENTS.md 保存 Agent 每次进入工作范围时都需要读取的稳定规则。按适用范围可以分为三层：

• 用户级：保存跨项目、长期稳定的个人协作偏好和安全边界。
• 项目级：保存当前仓库几乎所有任务都需要的项目事实、验证入口和全局约束。
• 子目录级：只补充某个包或目录独有的职责与约束，并与项目级规则共同生效。

**同一条规则只保留一个事实源。**详细参考知识放入独立文档 docs/，固定流程放入 Skill，可从代码、配置或 Schema 可靠获得的事实不写入 AGENTS.md。

以下模板用于起草；写入实际文件前，应替换所有 【】 占位内容，并删除示例说明、空章节和代码围栏。

维护核心就是记住AGENTS.md 是索引，新增的条目是否值得在每次任务中占用注意力。

用户级 AGENTS.md 模板

用户级文件的位置由 Agent 工具决定，例如 ~/.codex/AGENTS.md、~/AGENTS.md 或 ~/.claude/CLAUDE.md。

它只保存个人、跨项目、长期稳定的偏好，不记录具体仓库的技术栈、命令或目录结构。

不要根据一次会话自动重写用户级文件。

# 协作约定

## 工作目标

【用一句话说明希望 Agent 如何协助你，以及最重要的质量目标。】

## 决策原则

- 【最重要的取舍，例如：正确性优先于交付速度。】
- 【遇到信息不足时应如何处理。】
- 【何时应主动指出错误前提或高风险方案。】

## 沟通方式

- 【结论、依据和建议的顺序。】
- 【默认语言、语气和篇幅。】
- 【不确定性应如何表达，例如给出概率或明确标记推断。】
- 【常用输出格式，例如只输出步骤、表格、diff 或 JSON。】

## 工作方式

- 【开始工作前必须完成的调查。】
- 【修改既有内容时应优先遵循的原则。】
- 【何时需要先复现问题、制定计划或分析影响范围。】
- 【任务完成前必须覆盖的调用方、文档或其他交付物。】

## 验证标准

- 【行为变更需要什么级别的验证。】
- 【Bug 修复如何证明原问题不再出现。】
- 【无法运行验证时应如何报告。】

## 工具偏好

- 【跨项目稳定存在的命令或工具偏好。】
- 【特定类型任务应优先使用的工具。】
- 【禁止使用或只在特定条件下使用的工具。】

## 安全边界

- 【删除、覆盖、发布、推送或修改外部系统前的要求。】
- 【如何处理与当前任务无关的已有改动。】
- 【不得读取、写入或泄露的数据范围。】

## 文件维护

- 不要自动修改本文件；只有用户明确要求时才提出或执行修改。
- 项目事实和项目专属规则以仓库内的项目级 `AGENTS.md` 为准。

只有同时满足以下条件的内容才进入用户级文件：

• 跨多个项目适用
• 预计长期稳定
• 体现用户自己的判断
• 无法从当前仓库可靠推导。 含义相同的规则只保留一条。

项目级 AGENTS.md 模板

项目级文件位于仓库根目录，是项目会话的最小入口。初始文件通常只需要「项目」和「工具与验证」；只有存在真实、稳定的需求时，才增加其他章节。

# 项目

【用一句话说明项目是什么、服务谁，以及最重要的质量目标。】

## 工具与验证

- 包管理器：`【仅在默认选择不明确时填写】`
- 安装：`【仅填写非标准命令】`
- 构建：`【仅填写非标准命令】`
- 类型检查：`【仅填写非标准命令】`
- 测试：`【填写项目认可的最小验证命令】`

## 仓库级约束

- 【只填写适用于整个仓库、可执行且无法从代码可靠推导的规则。】
- 【安全关键规则可保留，即使触发频率较低。】
- 【新增普通规则应有重复会话证据，不为一次性失败追加规则。】

## 稳定领域概念

- `【术语】`：【只解释容易混淆且长期稳定的项目含义。】

## 按需指南

- 【语言或领域】：`【相对路径，例如 docs/TYPESCRIPT.md】`
- 【测试约定】：`【相对路径，例如 docs/TESTING.md】`
- 【固定工作流】：使用 `【Skill 名称或入口】`

## 局部规则

- 进入 `【子目录】` 后，读取该目录的 `AGENTS.md`。

根文件只保留几乎所有项目任务都需要的内容，以及安全、数据完整性或发布流程的关键约束。具体实现位置、标准配置已经声明的信息和一次性纠正不应写入根文件。

子目录 AGENTS.md 模板

只有子目录形成独立且稳定的工作范围时，才创建局部文件。子目录文件用于补充根文件，不重复项目级内容。

# 范围

【用一句话说明当前包或目录的职责。】

## 技术栈

- 【只填写该范围独有且无法从配置直接判断的信息。】

## 局部约束

- 【只填写进入该范围后才适用的规则。】

## 按需指南

- 【主题】：`【相对路径】`

最终文件应短小、稳定、可执行。 新增常驻规则前，先判断它是否应改放到子目录、独立文档或 Skill； 新增后还应检查重复、冲突、过时路径和空泛要求。

已有文档进行完善

用这段提示词修复有问题的 AGENTS.md

我希望你按照渐进式披露原则重构我的 AGENTS.md 文件。请遵循以下步骤：
1. 找出矛盾：识别所有相互冲突的指令。对于每一条矛盾，询问我希望保留哪个版本。
2. 识别核心内容：只提取应属于根目录 AGENTS.md 的内容：
   - 一句话的项目描述
   - 包管理器（如果不是 npm）
   - 非标准的构建/类型检查命令
   - 与每个任务都真正相关的内容
3. 归组其余内容：将剩余指令按逻辑类别组织（例如 TypeScript 约定、测试模式、API 设计、Git 工作流）。为每个类别创建独立的 markdown 文件。
4. 创建文件结构：输出：
   - 一个极简的根 AGENTS.md，其中包含指向各独立文件的 markdown 链接
   - 每个独立文件及其相关指令
   - 建议的 docs/ 目录结构
5. 标记应删除的内容：识别以下指令：
   - 冗余的（智能体已经知道的内容）
   - 过于模糊、无法执行的
   - 过于显而易见的（如"写出干净的代码"）

Skill 应该如何定位和管理

核心就一句话：低频 Skill 按需启用，避免长期占用固定上下文；常用的技能才全局用。

可以通过 skill-port cli 这个包进行管理。