# Agent 友好基础设施生成

接入包 v2 的核心扩展：从"分发固定模板"升级为"根据技术栈定制生成 Agent 友好基础设施"。
炼境扫描项目技术栈 → 用户确认 → 生成三件套（元规则 + 契约映射 + 工具派生格式）。

## 定位

现有接入包（v1）解决了"让项目被炼境感知"的问题。
本模块解决"让 agent 在项目里真正高效工作"的问题。

两者的关系：
- v1 是注册入炼境飞轮的门票
- v2 是项目内部 agent 工作环境的基础设施

## 生成的三件套

| 产物 | 用途 | 单一来源 |
|------|------|---------|
| `AGENTS.md`（元规则段落） | 跨工具通用的防腐约定 | 炼境统一版本，接入时写入 |
| `docs/ai-context/project-context.yaml` | 技术栈特定的契约路径映射 | 炼境扫描后生成，技术栈变更时重新生成 |
| `.claude/rules/doc-freshness.md` | Claude Code 的路径注入派生版 | 从 AGENTS.md 元规则自动派生 |

## 接入流程（扫描 → 确认 → 生成）

```
① 炼境扫描
   package.json / Cargo.toml / go.mod / Dockerfile
   → 识别框架、ORM、API 层、monorepo 结构

② 展示给用户确认（不跳过此步）
   "检测到：React 19 + Drizzle（drizzle/schema.ts）+ Hono（src/routes/）
    是否正确？"

③ 用户确认或手动修正

④ 定制化生成三件套
```

## 技术栈 → 契约路径映射规则

炼境内置识别表（示例，可扩展）：

| 识别条件 | 契约类型 | 默认路径 |
|---------|---------|---------|
| `prisma` in dependencies | 数据库 schema | `prisma/schema.prisma` |
| `drizzle-orm` in dependencies | 数据库 schema | `drizzle/schema.ts` |
| `hono` / `express` | API 接口 | `src/routes/**` |
| `openapi` / `swagger` | API 接口 | `openapi.yaml` |
| Rust + `axum` | API 接口 | `src/routes/` |
| pnpm workspace | 共享类型 | `packages/types/**` |

## 腐化监控（接入后持续运行）

炼境定期读取 git log，对比文档文件 vs 代码文件的最后修改时间：

| 风险级别 | 判断条件 |
|---------|---------|
| 🟢 正常 | 文档与代码同步更新 |
| 🟡 注意 | 核心代码改了，文档 14 天未动 |
| 🔴 高风险 | 外部契约类文件改了，AGENTS.md 30 天未动 |

技术栈变更感知：`package.json` / `Cargo.toml` 变化时主动提示"建议重新运行接入包生成"。

## 设计原则

- 元规则不含具体路径（技术栈无关），`project-context.yaml` 含路径（技术栈特定）
- 炼境生成，不要求用户手动维护多份格式
- 修复腐化永远是本地 agent 的事，炼境只检测和提醒

## 决策记录

- 元规则选用四支柱 + T1-T4 触发类型的双层结构：四支柱给 agent 判断"这个项目 ok 吗"，T1-T4 给 agent 判断"这次改动需要更新什么"
- project-context.yaml 选 YAML 而非写进 AGENTS.md：技术栈映射是易变信息，独立文件符合防腐铁律（不写死进常驻文档）
- 确认步骤不可跳过：项目可能正在迁移技术栈，扫描结果不一定是当前权威状态

## 参考验证

2026-06-29 用 enterprise-system 做模拟验证：
- 技术栈识别准确（React + Drizzle + Hono + PostgreSQL）
- 最近 git log 有 "chore(db): 彻底移除 Prisma，全面统一 Drizzle"，完美复现 T3 工具链变更场景
- project-context.yaml 不存在，验证了它需要炼境主动生成
- .claude/rules/ 已有 6 个路径注入规则，验证了派生格式的可行性

## 任务卡

> 本模块为 L 级，需先走 /architect 设计再拆分。以下为 concept 阶段的方向记录。

### 💭 技术栈扫描与确认 UI
- status: concept

### 💭 project-context.yaml 生成器
- status: concept

### 💭 AGENTS.md 元规则段落注入
- status: concept

### 💭 .claude/rules/ 派生生成
- status: concept

### 💭 腐化风险看板（文档新鲜度评分）
- status: concept

### 💭 技术栈变更感知与重新生成提示
- status: concept