AI Agent 技能定义（结合claude directory）CDR

🤖 AI Agent 技能定义：项目上下文管理器 (.aiWork) —— 优化落地版 v2

本版相对初版的核心变化：
加载策略从"按时间取最新"升级为 "feature 标签 + 中英文关键词召回 → recency 兜底"，解决多功能并行仓库下"漏掉相关上下文"的问题。
所有破例加载（proposed / review / draft）全部设上限，不再"无上限"，真正约束上下文预算。
文档新增 tags 与 keywords（允许中文）字段，从根上解决"中文意图 vs 英文文件名"匹配不上的问题。
requirements/ 与 decision/ 的破例逻辑对称：在研需求也可被召回。
concepts/ 改为按相关性召回，而非按时间。
front matter key 统一为 snake_case；新增 schema_version 以支持后续迁移。
补齐自增序号的并发/脏数据处理、根文件缺失处理、冷归档策略。

0. 全局配置参数（可调，集中管理）

为避免"魔法数字"散落各处，以下阈值集中定义，实现时可在 readme.md 顶部声明或由 skill 配置注入：

参数	默认值	含义
`FULL_LOAD_LIMIT`	3	`requirements/`、`decision/` 中主状态（approved/accepted）的全量加载上限
`BREAKGLASS_LIMIT`	3	破例加载上限（`proposed` / `review` / `draft`，匹配命中时）
`LIGHT_LOAD_LIMIT`	3	`drafts/`、`concepts/` 的轻量加载（仅元数据+标题）上限
`KEYWORD_MIN_OVERLAP`	1	判定"相关"所需的最小关键词重叠数
`SCHEMA_VERSION`	1	当前 `.aiWork` 规范版本号

1. 触发场景与意图识别

当用户发出开发指令时，系统首先通过本地文件系统状态 + 用户表达，识别两种边界：

【开始开发】意图
- 触发条件：用户提及"基于 decision|requirement 进行开发""开始某个需求开发"，且当前目录下不存在 .aiWork 文件夹。
- Agent 动作：判定为全新初始化。主动引导用户确认核心需求，并创建标准化的 .aiWork 目录结构及初始文件。
【继续开发】意图
- 触发条件：当前目录下已存在 .aiWork 文件夹，用户提及"继续开发 [某功能/需求]"。
- Agent 动作：判定为上下文恢复。先执行"当前功能关键词提取"（见 §4 Step 2.0），再按相关性加载历史归档。若用户提及的功能无法与现有文档或 todo.md 匹配，Agent 必须挂起任务并向用户追问确认，不得盲目猜测。

2. 标准化文件夹结构规范

AI 在项目根目录下创建 .aiWork 主目录。子目录、根文件及状态取值严格遵循以下约定。

📁 子目录及状态定义

requirements/（项目需求文档）
- Status 可选值：draft（草案）| review（评审中）| approved（已通过）| superseded（已废弃/被替代）| done（已交付）
drafts/（讨论记录与模糊点分析）
- Status 可选值：active（活跃中）| archived（已归档）
decision/（技术与工程决策记录 - ADR 风格）
- Status 可选值：proposed（提案中）| accepted（已接受）| superseded（已废弃/被取代）
- 核心要素：每条决策必须包含 "选了什么" / "备选是什么" / "为什么（权衡逻辑）"。
concepts/（通用背景知识与术语库）
- Status 可选值：stable（稳定可用）| outdated（已过时）

每个子目录下可选包含一个 archive/ 冷归档子目录（见 §5 归档策略）。

📄 根目录标准文件

todo.md：项目待办、待确认事项及任务勾选列表（唯一允许就地修改的文件）。
readme.md：说明该 .aiWork 结构的维护规范，并在顶部声明 schema_version。

3. 文件命名与格式规范

所有子文件夹内的文件严格执行"不可变时间线（Immutable Timeline）"原则。

命名规则

统一格式：[YYYYMMDD]-[NN]-[摘要].md
- 示例：20260609-01-auth-jwt.md
- 日期：以本地时区当天日期为准（团队跨时区时建议在 readme.md 中固定统一时区，如 UTC+8）。
- 序号 NN：两位数字、文件夹内自增。
  - 新序号 = max(该文件夹及其 archive/ 下所有「合规文件名」的序号) + 1。
  - 脏数据处理：不符合命名正则的文件不参与 max 计算，并在起飞前面板（§4 Step 3）中列出告警。
  - 冷归档不复用：max 计算必须同时扫描 archive/，确保归档后序号永不重用。
  - 序号不要求连续（删除/归档不影响）。
- 排序规则：按 YYYYMMDD 降序；同日期内按 NN 降序。
- 摘要：必须 kebab-case，3~5 个英文单词；用户未指定时由 AI 提取核心主题生成。

并发与撞号

写入采用 "create 即占用" 策略：以实际落盘文件名为准。
若目标文件名已存在（并发撞号），Agent 重新计算 max 序号并以下一个序号重试，禁止覆盖已有文件。

文档元数据块（snake_case 统一）

每篇文档头部必须包含标准 YAML Front Matter：

---
schema_version: 1
status: proposed                 # 取值见各目录定义
owner: <从 Git 配置或系统获取的用户名；非 git 环境回退系统用户名>
last_updated: 2026-06-09         # 任何状态/内容变更都必须同步刷新
tags: [order-refund, payment]    # feature/主题标签，kebab-case 英文，供按 feature 召回
keywords: [订单退款, 退款, refund] # 自由关键词，【允许中文】，供跨语言召回
# 以下为联动归档时按需追加：
# superseded_by: 20260610-02-xxx.md
# supersedes:    20260601-01-yyy.md
---
# kebab-case-title

设计要点：tags 走英文 kebab-case，与文件名摘要同构；keywords 允许中文，是"中文意图 → 文档"匹配的可靠通道。两者并存，召回时取并集。

4. 核心功能与操作流程（AI 执行算法）

触发本技能时，Agent 严格按以下流水线执行。

Step 1：环境检查与初始化

【开始开发】：创建缺失的子目录、archive/（按需）、todo.md、readme.md 基础模板。
【继续开发】：目录已存在则跳过创建，避免覆盖；缺失项静默补齐（见 §5）。

Step 2.0：当前功能关键词提取（继续开发时必做）

从用户指令中抽取"当前功能关键词集合 K"：

提取用户表达中的功能名词/短语（如"订单退款"）→ 直接纳入 K（保留中文原词）。
若能可靠归一化出英文等价词（如 order-refund / refund），一并纳入 K（best-effort，失败不影响）。
若用户未给出任何明确功能关键词，则 K = ∅，后续所有破例加载一律不触发，仅走 recency 兜底。

相关性判定：某文档与 K 相关 ⇔ K 与该文档的 (tags ∪ keywords ∪ 文件名摘要分词) 的重叠数 ≥ KEYWORD_MIN_OVERLAP（不区分大小写）。中文凭 keywords 命中，英文凭 tags/摘要命中。

Step 2：分级加载策略（相关性优先，recency 兜底）

加载分两个深度：

全量加载：完整内容进上下文。
轻量加载：仅 front matter + H1 标题进上下文；写代码遇到具体细节时再通过 Tool 按需精读。

`requirements/`

主池：status ∈ {approved, done}（忽略 superseded）。
- 相关性优先：主池中与 K 相关的文件 → 全量加载，按排序规则取前 FULL_LOAD_LIMIT 个。
- recency 兜底：若相关命中不足 FULL_LOAD_LIMIT（或 K = ∅），用主池中最新的文件补足到 FULL_LOAD_LIMIT。
破例（在研需求）：status ∈ {review, draft} 且与 K 相关的文件 → 全量加载，取前 BREAKGLASS_LIMIT 个。K = ∅ 时不加载任何 review/draft。

`decision/`

主池：status = accepted（忽略 superseded）。相关性优先 + recency 兜底，逻辑同上，上限 FULL_LOAD_LIMIT。
破例（待确认决策）：status = proposed 且与 K 相关的文件 → 全量加载，取前 BREAKGLASS_LIMIT 个（有上限，不再无限）。K = ∅ 时不加载任何 proposed。

`drafts/`

仅轻量加载。相关性优先（与 K 命中）+ recency 兜底，取前 LIGHT_LOAD_LIMIT 个。细节按需精读。

`concepts/`

仅轻量加载，且按相关性召回而非按时间：在 status = stable 中，取与 K 命中的前 LIGHT_LOAD_LIMIT 个。
K = ∅ 时不预加载 concepts；编码中遇到具体术语再按需全量精读对应文件。

不足上限时：任一池过滤后有效文件不足上限，则全部加载该池。

Step 3：起飞前状态检查（Pre-flight Check Dashboard）

进入实质编码前，Agent 必须输出简短的工作区健康度面板，列出所有卡点与隐患：

decision/ 中全部 proposed ADR（即使 Step 2 已加载部分，此处仍需完整列出，含未加载的）。
requirements/ 中全部 review/draft 需求（提示存在在研需求）。
todo.md 中所有未勾选的 - [ ] 事项。
命名脏数据告警：列出所有不符合命名正则、未参与序号计算的文件。

Step 4：联动更新与只读追加归档（Append-Only）

开发中发生变更/重构时，禁止直接覆写或擦除历史文档内容（todo.md 除外），必须执行"状态联动标记 + 指向性引用"。任何变更都要同步刷新被改文档的 last_updated。

决策变更（ADR 更新）：
1. 新建带最新时间戳的 ADR，status 设为 proposed 或 accepted；填好 tags/keywords。
2. 旧 ADR：status: superseded，追加 superseded_by: [新文件名]，刷新 last_updated。
3. 新 ADR：追加 supersedes: [旧文件名]。
需求变更（Requirement 更新）：
1. 新建带最新时间戳的需求，status 设为 approved 或 review；填好 tags/keywords。
2. 旧需求：status: superseded，追加 superseded_by: [新文件名]，刷新 last_updated。
3. 新需求：追加 supersedes: [旧文件名]，并在正文首段附 1~2 句 ## Change Log。
任务状态更新：允许对 todo.md 就地修改（In-place）打勾。

5. 异常与边界处理

有效文件不足：任一池过滤后不足对应上限，则全部加载。
子目录残缺：.aiWork 存在但缺个别子文件夹（如漏 concepts/），AI 静默补齐，不影响流程。
根文件残缺：todo.md 或 readme.md 缺失时，AI 静默按模板补齐（readme.md 须写入当前 schema_version）。
命名脏数据：不符合命名正则的文件不参与序号计算，并在起飞前面板中告警，不阻断流程。
并发撞号：见 §3，重算序号并以下一序号重试。
schema 版本不一致：若读到的文档 schema_version 低于当前 SCHEMA_VERSION，AI 应在面板中提示"建议迁移"，但仍按兼容方式读取，不强制阻断。
权限/读写失败：立即中断并抛出明确错误（权限不足、路径被占用等），禁止在无上下文记录的情况下盲目编码。

冷归档策略（控制无限增长）

进入终态且确认不再活跃的文件（superseded / 已结项的 done / outdated / archived）可由用户显式指令或周期性维护移入同级 archive/。
archive/ 内文件默认不自动加载，仅在用户明确要求时精读。
关键约束：序号 max 计算仍包含 archive/（见 §3），确保不可变时间线不被破坏、序号永不复用。

此版本在初版基础上修复了多功能仓库下的相关性召回、上下文预算约束、跨语言匹配、状态处理对称性、并发与归档等问题，内部约定自洽，可直接用于 AI Agent 实现。