---
title: plan-feature 阶段给的具体技术参数（env / 库 / 字段名）只能当占位，必须在 docs-main Step 0 Recon 阶段验证
date: 2026-05-19
tags: [workflow, plan-feature, docs-main, recon, drift, sso, issue-334]
---

# 场景

issue #334（Entra ID SSO）执行 `/plan-feature` 时，我在需求摘要里凭印象列了 env 命名：

```
【新增 env 变量】
- AZURE_AD_TENANT_ID
- AZURE_AD_CLIENT_ID
- AZURE_AD_CLIENT_SECRET
```

并把这份摘要原样传给 `/docs-main`。如果 docs-main 没强制 Step 0 Recon，4 个并行 Agent 会按 `AZURE_AD_*` 写 11 份文档，全部错——项目 `.env.example:218-226` 实际命名是 `AZURE_TENANT_ID`（不带 `_AD_`），`entra.service.ts:48` 已经在用这套 env，注释里还写了"用途：**SSO 登录**"。

幸运的是 docs-main Step 0 Recon 跑 grep 抓到了，我在 user-facing 汇报里以"纠正 1"形式停下来对齐后再发 Agent。

# 教训

**plan-feature 摘要里的具体技术参数（env / 库 / 字段名 / DB 列名）只能当占位，不能作为最终事实传给下游 skills。**

- ✅ plan-feature 摘要写："新增 env 变量控制 OIDC 回调地址 + JIT 域名白名单"（概念级）
- ❌ plan-feature 摘要写："新增 env `AZURE_AD_TENANT_ID` / `AZURE_AD_CLIENT_ID`"——除非已经 grep 过 `.env.example`

错的参数作为"事实卡"传给并行 Agent，N 份文档会同步漂错；事后被 doc-review 挑出来需要回炉。**plan-feature → docs-main 的串联里，docs-main 是"事实校验关卡"，不是直接施工**。

# 类似漂移其它例子（本 session 实际遇到）

- `passport-azure-ad` 库选型——微软 2023 已弃用，但我在 plan-feature 阶段没查 `backend/package.json`
- `zh-CN / en-US` locale 标识——项目 `frontend/src/lib/i18n.ts:7` 实际是 `zh / en`，docs Agent 全部错按 plan-feature 摘要写了双语版
- `lastSsoLoginAt` 字段——我在 plan-feature 阶段说"用户详情页加这个字段"，结果文档落地时一份说"从 AuditLog 反查"、一份当 DB 字段处理

# 行动准则

1. plan-feature **摘要给概念**，不给具体名字。即使用户在澄清问题里给了具体名字，也只是"待 Recon 验证"
2. docs-main Step 0 Recon **必须 grep 至少这 6 项**：
   - 相关 env：`grep -E "<前缀>" .env.example backend/src/**/*.service.ts`
   - 库版本：`cat backend/package.json | grep <相关>`
   - i18n locale 实际标识：`grep -E "type.*Locale" frontend/src/lib/i18n.ts`
   - DB 列名 + enum 实际值：`grep -E "@@map|enum " backend/prisma/schema/*.prisma`
   - 装饰器命名：`grep -rn "@RequirePermissions\|@Auditable" backend/src`
   - 现有错误码前缀：`grep -E "^export const.*=.*'.*_'" backend/src/**/error-codes*.ts`
3. docs-main 完成 Recon 后**主动在 user-facing 汇报里点名"纠正 plan-feature 摘要里 N 处"**——让用户看到漂移，能在 docs 落地前拉齐。本 session 我这么做了，避免了 4 个 Agent 漂错
4. 如果发现漂移 ≥ 2 处，docs-main 直接打回 plan-feature 重写摘要 / 或主进程显式 escape 出新事实卡再发 Agent

# 关联

- `.claude/skills/docs-main/SKILL.md` §0 — 项目惯例侦察清单（已有约束）
- `.claude/skills/plan-feature/SKILL.md` §1 — 读取上下文步骤（已要求"先读 .env.example / 现有模块文档"——但我执行时没读 .env.example，是流程偏离）
- `CLAUDE.md` §12 — 项目相关知识落项目文件
- `.learnings/2026-04-30-doc-review-multi-lens.md` — 4-lens 抓 sev-1 的对照