@pzy560117/codex-harness 0.1.3 → 0.1.5

package/package-source/docs/codex-harness-engineering/templates/docs/new-project-usage.md

@@ -6,9 +6,9 @@
 
 | 场景 | 推荐入口 | 说明 |
 | --- | --- | --- |
-| 第一次接入 Harness | `tools\\install/init-project.ps1` | thin 初始化 `AGENTS.md`、`tools/harness/*`、`.codex/`、`.codex-harness/`、`docs/ai/`、`docs/architecture/` 和 `docs/spec/` |
-| spec / plan 已确认，准备切主控 | `tools/harness/templates/project-task-template.json` -> `task.json` -> `tools/harness/codex-loop.ps1 -RunUntilDone` | 交互模式在这里结束，后续默认由 driver 接管 |
-| 单个需求串行实现 | `tools/harness/codex-loop.ps1 -RunUntilDone` | 一个 Git 工作区里按 `task.json` 优先级逐个完成任务 |
+| 第一次接入 Harness | `tools\\install/init-project.ps1` | thin 初始化 `AGENTS.md`、`tools/harness/*`、`.codex/`、`.codex-harness/`、`docs/ai/`、`docs/architecture/` 和 `docs/spec/` |
+| spec / plan 已确认，准备切主控 | `tools/harness/templates/project-task-template.json` -> `task.json` -> `tools/harness/codex-loop.ps1 -RunUntilDone` | 交互模式在这里结束，后续默认由 driver 接管 |
+| 单个需求串行实现 | `tools/harness/codex-loop.ps1 -RunUntilDone` | 一个 Git 工作区里按 `task.json` 优先级逐个完成任务 |
 | 需要沉淀项目经验 | `docs/knowledge/knowledge-catalog.md` -> `ARCHIVE-001` | 任务结束后把可复用经验归档为知识条目 |
 | 既有项目冷启动知识库 | `docs/harness/knowledge-import.md` | 从 README、docs、代码结构、issue/review 中提取 draft 条目 |
 | 维护知识库健康 | `docs/harness/knowledge-lint.md` | 检查索引、孤儿条目、重复、冲突、成熟度和长期未引用条目 |
@@ -20,39 +20,67 @@
 
 | 模式 | 命令入口 | 输出内容 |
 | --- | --- | --- |
-| `project` | `tools\\install/init-project.ps1` / `tools\\install/install-agent.ps1 -ProjectRoot . -Scope project` | 新默认 thin project 入口，只输出项目运行必需内容 |
-| `full` | `tools\\install/install-agent.ps1 -Mode full` | 显式 legacy full 入口，同时安装项目 runtime、`.agents/` vendor 包和共享资源 |
-| `vendor` | `tools\\install/install-agent.ps1 -Mode vendor` / `tools\\install/install-agent.ps1 -Scope vendor` | 只复制 `.agents/` vendor 包，适合离线或强隔离场景 |
-| `user` | `tools\\install/install-user.ps1` / `tools\\install/install-agent.ps1 -Scope user` | 只写入 `%USERPROFILE%/.codex/packages/codex-harness/` 下的 package source 和 user lock |
-
-`full` 行为作为显式 legacy 兼容入口保留。当前包已经提供 package lock、只读升级/卸载计划、安全 `-Upgrade` 和 vendor `-Uninstall`。新分层入口优先使用 wrapper 或等价 `-Scope user|project|vendor` 命令：`tools\\install/install-user.ps1` 等价于 `tools\\install/install-agent.ps1 -Scope user`，`tools\\install/init-project.ps1` 等价于 `tools\\install/install-agent.ps1 -ProjectRoot . -Scope project`。当前不提供 `harness install-user` 子命令。当前不提供 `harness init-project` 子命令。Windows PowerShell 主链路请直接运行这两个 wrapper，避免误以为存在独立 CLI。`-Scope project` 与无参数 `tools\\install/install-agent.ps1 -ProjectRoot .` 等价，都是新项目默认 thin 输出，只生成项目运行必需 runtime、项目级 `.agents/` active surface、`.codex/`、`.codex-harness/state/config.json`、`.codex-harness/locks/package.lock.json`、`.codex-harness/manifests/install-manifest.json`、`docs/ai/`、`docs/architecture/constraints.md`、`docs/spec/01..14` 和 `tools/`，不复制完整 vendor 镜像、`docs/harness/`、`docs/testing/`、`docs/knowledge/` 或 `docs/requirement-prep-kit/`。`-Scope user` 只安装用户级 package source 并写入用户级 lock。
+| `project` | `tools\\install/init-project.ps1` / `tools\\install/install-agent.ps1 -ProjectRoot . -Scope project` | 新默认 thin project 入口，只输出项目运行必需内容 |
+| `full` | `tools\\install/install-agent.ps1 -Mode full` | 显式 legacy full 入口，同时安装项目 runtime、`.agents/` vendor 包和共享资源 |
+| `vendor` | `tools\\install/install-agent.ps1 -Mode vendor` / `tools\\install/install-agent.ps1 -Scope vendor` | 只复制 `.agents/` vendor 包，适合离线或强隔离场景 |
+| `user` | `tools\\install/install-user.ps1` / `tools\\install/install-agent.ps1 -Scope user` | 只写入 `%USERPROFILE%/.codex/packages/codex-harness/` 下的 package source 和 user lock |
+
+`full` 行为作为显式 legacy 兼容入口保留。当前包已经提供 package lock、只读升级/卸载计划、安全 `-Upgrade` 和 vendor `-Uninstall`。新分层入口优先使用 wrapper 或等价 `-Scope user|project|vendor` 命令：`tools\\install/install-user.ps1` 等价于 `tools\\install/install-agent.ps1 -Scope user`，`tools\\install/init-project.ps1` 等价于 `tools\\install/install-agent.ps1 -ProjectRoot . -Scope project`。当前不提供 `harness install-user` 子命令。当前不提供 `harness init-project` 子命令。Windows PowerShell 主链路请直接运行这两个 wrapper，避免误以为存在独立 CLI。`-Scope project` 与无参数 `tools\\install/install-agent.ps1 -ProjectRoot .` 等价，都是新项目默认 thin 输出，只生成项目运行必需 runtime、项目级 `.agents/` active surface、`.codex/`、`.codex-harness/state/config.json`、`.codex-harness/locks/package.lock.json`、`.codex-harness/manifests/install-manifest.json`、`docs/ai/`、`docs/architecture/constraints.md`、`docs/spec/01..14` 和 `tools/`，不复制完整 vendor 镜像、`docs/harness/`、`docs/testing/`、`docs/knowledge/` 或 `docs/requirement-prep-kit/`。`-Scope user` 只安装用户级 package source 并写入用户级 lock。
+
+## `docs/ai/` 导航层
+
+- `repo-map.md`
+- `architecture-brief.md`
+- `CURRENT_TASK.md`
+- `PROJECT_CONTEXT.md`
+- `DECISIONS.md`
+- `API_MAP.md`
+- `DB_SCHEMA.md`
+- `KNOWN_ISSUES.md`
+- `CHANGELOG_AI.md`
+
+推荐顺序：
+
+1. 先裁剪 `repo-map.md` 和 `architecture-brief.md`
+2. 再补 `CURRENT_TASK.md`
+3. 复杂项目再补 `PROJECT_CONTEXT.md`、`DECISIONS.md`、`API_MAP.md`、`DB_SCHEMA.md`
+4. 把长期可复用经验沉淀到 `docs/knowledge/*`
+
+接入完成后，建议再确认项目最小文档集是否齐全：
+
+- `AGENTS.md`
+- `README.md`
+- `docs/architecture/constraints.md` 或等价架构 truth source
+- `docs/ai/repo-map.md`
+- `docs/ai/CURRENT_TASK.md`
+- `docs/testing/TEST_STRATEGY.md`
 
 ```powershell
-powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\\install/install-user.ps1
-powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\\install/init-project.ps1
-powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\\install/install-agent.ps1 -ProjectRoot . -Scope vendor
+powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\\install/install-user.ps1
+powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\\install/init-project.ps1
+powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\\install/install-agent.ps1 -ProjectRoot . -Scope vendor
 ```
 
-直接运行 `tools\\install/bootstrap-codex-harness.ps1` 或旧 `-Mode project` 仍使用 legacy profile，适合需要保留完整 harness 文档包的旧项目；新项目默认使用 `tools\\install/init-project.ps1` 或等价 `-ProjectRoot . -Scope project`。
+直接运行 `tools\\install/bootstrap-codex-harness.ps1` 或旧 `-Mode project` 仍使用 legacy profile，适合需要保留完整 harness 文档包的旧项目；新项目默认使用 `tools\\install/init-project.ps1` 或等价 `-ProjectRoot . -Scope project`。
 
 `tools/harness/doctor.ps1` 会按 `installScope=project` 检查 thin 输出：缺少 `.codex-harness/manifests/install-manifest.json` 会提示 warning，snapshot JSON 非法、`docs/architecture/constraints.md` 或 `docs/spec/01..14` 缺失会失败；发现 `.agents/`、`docs/harness/`、`docs/testing/`、`docs/knowledge/` 或 `docs/requirement-prep-kit/` 时只提示 legacy 残留 warning，不会自动删除。
 
 Phase 7 切换门禁先看 doctor 的 readiness 汇总：
 
 - `Readiness gate: PASS` 且 `ProjectShape: thin-project`：项目已满足 thin 前置条件。
-- `ProjectShape: thin-project-missing-user-package`：先运行 `powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\\install/install-user.ps1`，再重新运行 `tools/harness/doctor.ps1`。
+- `ProjectShape: thin-project-missing-user-package`：先运行 `powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\\install/install-user.ps1`，再重新运行 `tools/harness/doctor.ps1`。
 - `ProjectShape: thin-project-with-legacy-residue` 或 `legacy-full-project`：先运行 `-MigratePlan` 查看分类，再按报告决定是否运行 `-MigrateApply -Confirm`。
-- `ProjectShape: vendor-project`：保留 vendor 模式时运行 `powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\\install/install-agent.ps1 -ProjectRoot . -Scope vendor` 或重新运行 `tools/harness/doctor.ps1` 复核 drift。
-- `ProjectShape: not-installed`：先运行 `powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\\install/init-project.ps1`。
+- `ProjectShape: vendor-project`：保留 vendor 模式时运行 `powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\\install/install-agent.ps1 -ProjectRoot . -Scope vendor` 或重新运行 `tools/harness/doctor.ps1` 复核 drift。
+- `ProjectShape: not-installed`：先运行 `powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\\install/init-project.ps1`。
 
 readiness gate 只读；它只报告阻断项和 `FixCommand`，不会自动安装、迁移、删除或覆盖项目文件。
 
 已有 legacy `.agents/` 项目不要直接清理目录。先运行只读迁移计划：
 
 ```powershell
-powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\\install/install-agent.ps1 -ProjectRoot . -MigratePlan
-powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\\install/install-agent.ps1 -ProjectRoot . -MigrateApply
-powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\\install/install-agent.ps1 -ProjectRoot . -MigrateApply -Confirm
+powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\\install/install-agent.ps1 -ProjectRoot . -MigratePlan
+powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\\install/install-agent.ps1 -ProjectRoot . -MigrateApply
+powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\\install/install-agent.ps1 -ProjectRoot . -MigrateApply -Confirm
 ```
 
 操作顺序固定为：
@@ -74,15 +102,15 @@ powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\\install/install-age
 已安装项目先用只读计划判断风险：
 
 ```powershell
-powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\\install/install-agent.ps1 -ProjectRoot . -UpgradePlan
-powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\\install/install-agent.ps1 -ProjectRoot . -UninstallPlan
+powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\\install/install-agent.ps1 -ProjectRoot . -UpgradePlan
+powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\\install/install-agent.ps1 -ProjectRoot . -UninstallPlan
 ```
 
 计划中没有 `blocked-user-drift` 时，才执行写入命令：
 
 ```powershell
-powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\\install/install-agent.ps1 -ProjectRoot . -Upgrade
-powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\\install/install-agent.ps1 -ProjectRoot . -Uninstall
+powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\\install/install-agent.ps1 -ProjectRoot . -Upgrade
+powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\\install/install-agent.ps1 -ProjectRoot . -Uninstall
 ```
 
 `-Upgrade` 只覆盖 lock 记录中未发生用户 drift 的不可变文件，并刷新 `.codex-harness/locks/package.lock.json`。`-Uninstall` 只删除 lock 中 `scope=vendor` 的 managed files，保留 project scope 和 user scope。
@@ -106,18 +134,21 @@ powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\\install/install-age
 3. 如果是 legacy 未分类文件，保留现状，等后续独立任务补逐项确认机制。
 4. 如果 dry-run 出现非空 `actualWrites`，说明执行边界异常，停止继续操作并回退到计划阶段排查。
 
-## 1. 初始化
-
-```powershell
-git status --short
-powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\\install/init-project.ps1
-powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\\harness/doctor.ps1
-```
+## 1. 初始化
+
+```powershell
+git status --short
+powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\\install/init-project.ps1
+powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\\install/env-check.ps1
+powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\\harness/doctor.ps1
+```
+
+如果项目存在 `build`、`lint`、`test`、`typecheck`、`docker build` 或 CI workflow，首次接入时应同时把这些命令和环境变量依赖补到 `docs/harness/env-and-deployment-template.md`，不要只留在 `package.json` 或 CI 配置里。
 
 ## 2. 创建任务
 
 ```powershell
-Copy-Item .\tools\harness\templates\tools/harness/templates/project-task-template.json .\task.json
+Copy-Item .\tools\harness\templates\tools/harness/templates/project-task-template.json .\task.json
 ```
 
 建议 `runtime.git` 使用：
@@ -129,21 +160,54 @@ Copy-Item .\tools\harness\templates\tools/harness/templates/project-task-templat
 }
 ```
 
-## 3. 运行 Driver
-
-```powershell
-powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\\harness/codex-loop.ps1 -RunUntilDone
-```
-
-- `.codex/agents/*.toml` 同时提供只读辅助子代理和写入型 worker 子代理。
+## 3. 运行 Driver
+
+```powershell
+powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\\harness/codex-loop.ps1 -RunUntilDone
+```
+
+### 3.1 内容门禁怎么配
+
+建议在项目 `task.json` 里显式写出默认门禁档位：
+
+```json
+{
+  "runtime": {
+    "content_gates": {
+      "default_mode": "core"
+    }
+  }
+}
+```
+
+门禁分层：
+
+- `core`：默认档位，适合新项目冷启动
+- `recommended`：适合团队已经稳定维护文档和测试 truth source 的项目
+- `full`：只适合非常重治理的项目，不建议作为新项目默认值
+- `risk_tags`：只给高风险任务启用专项门禁，例如 `security`、`data`、`integration`、`mobile`
+
+示例：
+
+```json
+{
+  "id": "ORDER-001",
+  "task_kind": "feature_impl",
+  "risk_tags": ["security", "data"]
+}
+```
+
+- `.codex/agents/*.toml` 同时提供只读辅助子代理和写入型 worker 子代理。
 - 这些子代理开始前必须先读 `AGENTS.md`、`docs/harness/task-session-strategy.md`、`.codex/rules/agents.md` 和对应 `.agents/skills/*/SKILL.md`（如存在）。
 - 如果是被 stop hook 拦下后继续执行的下一轮，也先按上面这组文档重读一遍，再决定是否启用子代理。
 - 如果主控需要更新 `task.json`、`AGENTS.md`、`.codex/*`、`.codex/rules/*`、`docs/harness/*`、prompt 或其他非 driver 内容，必须委派 `harness-writer`、`docs-worker` 或匹配的实现 worker，不能由主控会话自己写。
-- 目标项目的 `.agents/` 默认不再复制项目运行时用的 `.codex/` 或 `docs/harness/`；这些内容直接安装到项目根。为了支持安装后的再次 bootstrap，`.agents/docs/codex-harness-engineering/templates/` 会保留模板复制源。
-- `docs/knowledge/` 是项目级知识层；实现会话按 `knowledge-catalog.md`、`catalog.md`、具体条目的顺序按需读取，归档任务负责更新索引。
-- 已有项目接入时，可先按 `docs/harness/knowledge-import.md` 冷启动 5-13 条 draft 知识；导入过程用 `import-state.json` 或导入报告记录 processed/pending/skipped/low_confidence 来源和 resume cursor，后续任务通过引用和验证逐步提升成熟度。
-- 每隔一段任务后，按 `docs/harness/knowledge-lint.md` 检查索引一致、重复、冲突和长期未引用条目。
-- 如果团队维护独立知识库，按 `docs/harness/team-knowledge-sync.md` 把跨项目候选写入 `contributions/pending/`；该同步失败只能降级为候选报告，不能阻塞本地实现验证。
+- 目标项目的 `.agents/` 默认不再复制项目运行时用的 `.codex/` 或 `docs/harness/`；这些内容直接安装到项目根。为了支持安装后的再次 bootstrap，`.agents/docs/codex-harness-engineering/templates/` 会保留模板复制源。
+- `docs/ai/` 是项目导航层；默认先读 `repo-map.md`、`architecture-brief.md`、`CURRENT_TASK.md`。
+- `docs/knowledge/` 是项目级知识层；实现会话按 `knowledge-catalog.md`、`catalog.md`、具体条目的顺序按需读取，归档任务负责更新索引。
+- 已有项目接入时，可先按 `docs/harness/knowledge-import.md` 冷启动 5-13 条 draft 知识；导入过程用 `import-state.json` 或导入报告记录 processed/pending/skipped/low_confidence 来源和 resume cursor，后续任务通过引用和验证逐步提升成熟度。
+- 每隔一段任务后，按 `docs/harness/knowledge-lint.md` 检查索引一致、重复、冲突和长期未引用条目。
+- 如果团队维护独立知识库，按 `docs/harness/team-knowledge-sync.md` 把跨项目候选写入 `contributions/pending/`；该同步失败只能降级为候选报告，不能阻塞本地实现验证。
+- 如果需要接入 MCP、外部文档或代码语义工具，先读 `docs/harness/mcp-knowledge-governance.md` 和 `docs/harness/code-semantics-and-navigation.md`。
 
 ## 4. UI 项目要求
 

package/package-source/docs/codex-harness-engineering/templates/docs/project-agents-template.md

@@ -1,154 +1,211 @@
-# Project AGENTS.md Template
-
-本文是生成项目根 `AGENTS.md` 的通用模板，不应原样复制后长期保留占位符。生成时先分析项目事实，再按项目类型裁剪章节。
-
-## 使用原则
-
-- `AGENTS.md` 是给编码 Agent 的入口规则，不是 README 的复刻。
-- 只写会改变 Agent 行为的项目特定信息；通用工程常识、formatter/linter 已覆盖的内容不要写。
-- 根 `AGENTS.md` 保持短入口，建议 60-120 行；细节放到 `docs/`、`rules/`、`specs/` 或测试文档，并在入口索引引用。
-- 每条禁令必须给替代方案；不能说明替代方案的内容先写成风险或待确认项。
-- 可以自动检查的规则优先进入 lint、schema、hook、CI、verify 脚本，不只依赖文字提醒。
-- 规则从 Bad Case 迭代：重复 review 问题、线上事故、新人必踩坑、Agent 反复犯错，才升级为入口规则。
-- `project_doc_fallback_filenames` 只在目录缺少 `AGENTS.md` 时生效；生成了根 `AGENTS.md` 的项目，不要再依赖 fallback 文件作为额外入口。
-- 不用 `developer_instructions` 或 `model_instructions_file` 承载普通项目规则；这些是 config 层上下文入口，默认应保持为空。
-
-## 生成前事实扫描
-
-先收集这些事实，再填模板：
-
-| 事实 | 来源 |
-| --- | --- |
-| 项目类型 | README、目录结构、启动脚本、部署文件 |
-| 技术栈 | `package.json`、`pyproject.toml`、`go.mod`、`pom.xml`、Dockerfile |
-| 常用命令 | scripts、Makefile、CI、现有 docs |
-| 架构边界 | `src/`、`apps/`、`packages/`、`services/`、`docs/architecture*` |
-| 代码地图 | `docs/ai/repo-map.md`、`codemaps/*`、架构索引或模块清单 |
-| 测试入口 | test scripts、`tests/`、Playwright/Cypress/Pytest/Vitest 配置 |
-| 自动化检查 | linter、formatter、typecheck、CI、hooks |
-| 私域知识 | 内部组件库、私有 API、特殊目录、历史迁移约束 |
-| Bad Case | 近期 review、bug 标签、trace、失败复盘、团队反复纠正事项 |
-
-## 根 AGENTS.md 模板
-
-```markdown
-# AGENTS.md
-
-本文件只保留当前项目中每次编码会话都必须知道的规则。更详细的背景、接口、测试和部署说明见下方索引。
-
-## 项目边界
-
-- 项目类型：<应用 / 库 / monorepo / harness / 模板 / 服务端 / 前端 / 全栈>
-- 主要技术栈：<只列非默认且会影响实现选择的技术>
-- 真实入口：<启动、构建、测试、driver 或任务系统入口>
-- 代码地图：`<docs/ai/repo-map.md 或同类导航文件>`；需要理解模块位置时先读它，再进入具体目录。
-- 不要把 README 的业务介绍复制到这里；README 回答“项目是什么”，本文件回答“Agent 怎么改”。
-
-## 常用命令
-
-| 场景 | 命令 | 说明 |
-| --- | --- | --- |
-| 安装 | `<command>` | <必要前提或包管理器> |
-| 开发 | `<command>` | <端口 / 环境变量 / mock 说明> |
-| 测试 | `<command>` | <默认测试范围> |
-| 类型 / lint | `<command>` | <失败时处理方式> |
-| 构建 | `<command>` | <产物路径或限制> |
-
-## 架构与目录规则
-
-| 场景 | 应使用 | 不要使用 |
-| --- | --- | --- |
-| <例如 API 入口> | `<path/helper>` | <禁止路径或绕路方式> |
-| <例如状态管理> | `<existing-pattern>` | <不要引入的新库> |
-| <例如数据访问> | `<repository/service>` | <不要跨层调用> |
-
-## 项目硬约束
-
-- <CRITICAL 规则 1>；替代方案：<明确可执行做法>。
-- <CRITICAL 规则 2>；替代方案：<明确可执行做法>。
-- <安全 / 数据 / 权限 / 迁移 / 发布红线>；替代方案：<明确可执行做法>。
-
-## 测试与完成定义
-
-- 修改 <模块/路径> 后至少运行 `<command>`。
-- 涉及 <API/业务流/权限/支付/外部系统> 时，必须补充 <单元/集成/E2E/契约/真实环境 smoke> 证据。
-- 完成声明必须包含实际运行过的命令和结果；不要只说“应该可以”。
-
-## 工作区与提交
-
-- 开始前检查 `git status --short`；不要覆盖用户未说明的改动。
-- 只修改与当前任务相关的文件。
-- 禁止使用破坏性 Git 命令，除非用户明确要求。
-- 提交前运行与改动匹配的验证命令。
-
-## 深文档索引
-
-- 架构：`<docs/architecture.md>`
-- 代码地图：`<docs/ai/repo-map.md>`
-- API / 契约：`<docs/api.md>`
-- 测试策略：`<docs/testing.md>`
-- 部署 / 运维：`<docs/deploy.md>`
-- 历史坑 / 项目知识：`<docs/knowledge/>`
-```
-
-## 子目录 AGENTS.md 模板
-
-只有 monorepo 或目录规则明显不同时才添加子目录 `AGENTS.md`。子目录规则应比根规则更具体。
-
-````markdown
-# <path> AGENTS.md
-
-## 作用范围
-
-- 本文件只适用于 `<path>/` 下的改动。
-- 根 `AGENTS.md` 仍然有效；本文件只补充或收紧本目录规则。
-
-## 本目录约束
-
-- 技术栈 / 框架：<目录特定信息>
-- 入口文件：<真实入口>
-- 测试命令：<目录级验证命令>
-
-## 决策表
-
-| 场景 | 应使用 | 不要使用 |
-| --- | --- | --- |
-| <场景> | <本目录模式> | <禁止做法> |
-
-## 代码示例
-
-```<language>
-// 3-10 行真实项目代码，展示应该复用的模式
-```
-````
-
-## CLAUDE.md 组合模板
-
-仅当团队主要使用 Claude Code 且需要 Claude 专属能力时添加。通用规则仍放 `AGENTS.md`。
-
-```markdown
-# CLAUDE.md
-
-@AGENTS.md
-
-## Claude Code 专属规则
-
-- 使用 hooks / commands / memory 的项目约定：<只写 Claude Code 独有内容>。
-- 个人本地偏好放 `CLAUDE.local.md`，不要提交。
-- 不要在这里重复 `AGENTS.md` 已有规则。
-```
-
-## 裁剪检查
-
-生成后逐条检查：
-
-| 检查项 | 处理 |
-| --- | --- |
-| 是否超过 120 行 | 下沉细节到深文档，只保留索引 |
-| 是否复制 README 项目介绍 | 删除，改为 README 链接 |
-| 是否包含通用编码常识 | 删除 |
-| 是否缺少代码地图入口 | 新增 `docs/ai/repo-map.md` 或说明为什么项目太小不需要 |
-| 禁令是否没有替代方案 | 补替代方案或降级为风险 |
-| 是否引用不存在的命令或路径 | 修正或删除 |
-| 自动化可检查的内容是否只写文字 | 补充脚本 / hook / CI / verify 入口 |
-| 深文档是否无法从入口发现 | 加入索引 |
+# Project AGENTS.md Template
+
+本文是生成项目根 `AGENTS.md` 的通用模板，不应原样复制后长期保留占位符。生成时先分析项目事实，再按项目类型裁剪章节。
+
+## 使用原则
+
+- `AGENTS.md` 是给编码 Agent 的入口规则，不是 README 的复刻。
+- 只写会改变 Agent 行为的项目特定信息；通用工程常识、formatter/linter 已覆盖的内容不要写。
+- 根 `AGENTS.md` 保持短入口，建议 60-120 行；细节放到 `docs/`、`rules/`、`specs/` 或测试文档，并在入口索引引用。
+- 根 `AGENTS.md` 只写全项目都成立的入口规则；目录独有的模块职责、边界、入口、测试命令、坑点和禁止事项，优先写进最接近该目录的子目录 `AGENTS.md`。
+- 如果项目同时维护模板源、镜像和运行时副本，先确认哪一份是 canonical；默认优先修改模板 canonical，再同步活跃副本，不要只修当前工作区现状。
+- 每条禁令必须给替代方案；不能说明替代方案的内容先写成风险或待确认项。
+- 可以自动检查的规则优先进入 lint、schema、hook、CI、verify 脚本，不只依赖文字提醒。
+- 规则从 Bad Case 迭代：重复 review 问题、线上事故、新人必踩坑、Agent 反复犯错，才升级为入口规则。
+- `project_doc_fallback_filenames` 只在目录缺少 `AGENTS.md` 时生效；生成了根 `AGENTS.md` 的项目，不要再依赖 fallback 文件作为额外入口。
+- 不用 `developer_instructions` 或 `model_instructions_file` 承载普通项目规则；这些是 config 层上下文入口，默认应保持为空。
+
+## 生成前事实扫描
+
+先收集这些事实，再填模板：
+
+| 事实 | 来源 |
+| --- | --- |
+| 项目类型 | README、目录结构、启动脚本、部署文件 |
+| 技术栈 | `package.json`、`pyproject.toml`、`go.mod`、`pom.xml`、Dockerfile |
+| 常用命令 | scripts、Makefile、CI、现有 docs |
+| 架构边界 | `src/`、`apps/`、`packages/`、`services/`、`docs/architecture*` |
+| 代码地图 | `docs/ai/repo-map.md`、`codemaps/*`、架构索引或模块清单 |
+| 测试入口 | test scripts、`tests/`、Playwright/Cypress/Pytest/Vitest 配置 |
+| 自动化检查 | linter、formatter、typecheck、CI、hooks |
+| 命名与业务词典 | `docs/harness/code-style-and-naming.md`、`docs/code-style.md`、接口 / 数据字典 |
+| 私域知识 | 内部组件库、私有 API、特殊目录、历史迁移约束 |
+| Bad Case | 近期 review、bug 标签、trace、失败复盘、团队反复纠正事项 |
+
+最小核心文档集建议至少覆盖：
+
+- `AGENTS.md`
+- `README.md`
+- `docs/architecture.md`
+- `docs/code-style.md`
+- `docs/api-convention.md`
+- `docs/component-map.md`
+- `docs/test-strategy.md`
+- `docs/current-task.md`
+
+## 根 AGENTS.md 模板
+
+```markdown
+# AGENTS.md
+
+本文件只保留当前项目中每次编码会话都必须知道的规则。更详细的背景、接口、测试和部署说明见下方索引。
+
+## 项目边界
+
+- 项目类型：<应用 / 库 / monorepo / harness / 模板 / 服务端 / 前端 / 全栈>
+- 主要技术栈：<只列非默认且会影响实现选择的技术>
+- 真实入口：<启动、构建、测试、driver 或任务系统入口>
+- 代码地图：`<docs/ai/repo-map.md 或同类导航文件>`；需要理解模块位置时先读它，再进入具体目录。
+- 如果存在目录级 `AGENTS.md`：进入对应目录后同时遵守根规则和本地规则。
+- 不要把 README 的业务介绍复制到这里；README 回答“项目是什么”，本文件回答“Agent 怎么改”。
+
+## 模板与 Canonical
+
+- 如果仓库同时存在模板源、运行时副本、镜像或 package-assets：先说明哪一份是 canonical。
+- 默认修改顺序：`<template canonical>` -> `<active mirror>` -> `<runtime copy>`。
+- 不要只修当前工作区现状而漏掉模板源。
+
+## 常用命令
+
+| 场景 | 命令 | 说明 |
+| --- | --- | --- |
+| 安装 | `<command>` | <必要前提或包管理器> |
+| 开发 | `<command>` | <端口 / 环境变量 / mock 说明> |
+| 测试 | `<command>` | <默认测试范围> |
+| 类型 / lint | `<command>` | <失败时处理方式> |
+| 构建 | `<command>` | <产物路径或限制> |
+
+## 架构与目录规则
+
+| 场景 | 应使用 | 不要使用 |
+| --- | --- | --- |
+| <例如 API 入口> | `<path/helper>` | <禁止路径或绕路方式> |
+| <例如状态管理> | `<existing-pattern>` | <不要引入的新库> |
+| <例如数据访问> | `<repository/service>` | <不要跨层调用> |
+
+常见可直接复用的规则样板：
+
+```text
+前端：
+- 页面只负责展示和组合
+- 业务逻辑放 hooks
+- 接口请求放 services
+- 类型放 types
+- 常量放 constants
+- 公共组件放 components/common
+
+后端：
+- Controller 只处理请求和响应
+- Service 处理业务逻辑
+- Repository/DAO 处理数据库
+- DTO 处理输入输出结构
+```
+
+## 项目硬约束
+
+- <CRITICAL 规则 1>；替代方案：<明确可执行做法>。
+- <CRITICAL 规则 2>；替代方案：<明确可执行做法>。
+- <安全 / 数据 / 权限 / 迁移 / 发布红线>；替代方案：<明确可执行做法>。
+
+常见禁止事项样板：
+
+```text
+- 禁止在页面组件中直接请求接口；替代方案：统一走 services / API client。
+- 禁止重复封装 axios/fetch；替代方案：复用现有 HTTP client。
+- 禁止在公共组件里写业务逻辑；替代方案：把业务逻辑下沉到 feature 或 hooks。
+- 禁止绕过权限系统；替代方案：复用既有权限入口或 policy。
+- 禁止新增 utils2、common2、helper2 这类目录；替代方案：放回既有模块或补目录级规则后再新增。
+```
+
+## 测试与完成定义
+
+- 修改 <模块/路径> 后至少运行 `<command>`。
+- 涉及 <API/业务流/权限/支付/外部系统> 时，必须补充 <单元/集成/E2E/契约/真实环境 smoke> 证据。
+- 完成声明必须包含实际运行过的命令和结果；不要只说“应该可以”。
+
+## 工作区与提交
+
+- 开始前检查 `git status --short`；不要覆盖用户未说明的改动。
+- 只修改与当前任务相关的文件。
+- 禁止使用破坏性 Git 命令，除非用户明确要求。
+- 提交前运行与改动匹配的验证命令。
+
+## 深文档索引
+
+- 架构：`<docs/architecture.md>`
+- 代码地图：`<docs/ai/repo-map.md>`
+- 代码风格 / 命名：`<docs/harness/code-style-and-naming.md 或 docs/code-style.md>`
+- API / 契约：`<docs/api.md>`
+- 测试策略：`<docs/testing.md>`
+- 部署 / 运维：`<docs/deploy.md>`
+- 历史坑 / 项目知识：`<docs/knowledge/>`
+```
+
+## 子目录 AGENTS.md 模板
+
+只有 monorepo 或目录规则明显不同时才添加子目录 `AGENTS.md`。子目录规则应比根规则更具体。
+
+````markdown
+# <path> AGENTS.md
+
+## 作用范围
+
+- 本文件只适用于 `<path>/` 下的改动。
+- 根 `AGENTS.md` 仍然有效；本文件只补充或收紧本目录规则。
+
+## 本目录约束
+
+- 本目录负责什么：<职责>
+- 本目录不负责什么：<边界>
+- 技术栈 / 框架：<目录特定信息>
+- 入口文件：<真实入口>
+- 修改前必须先看：<核心文件 / 规则 / 测试>
+- 测试命令：<目录级验证命令>
+- 常见复用对象：<组件 / hook / service / helper / fixture>
+
+## 决策表
+
+| 场景 | 应使用 | 不要使用 |
+| --- | --- | --- |
+| <场景> | <本目录模式> | <禁止做法> |
+| 复用同类能力 | <已有组件 / hook / service / helper> | <重复新建一套实现> |
+
+## 代码示例
+
+```<language>
+// 3-10 行真实项目代码，展示应该复用的模式
+```
+````
+
+## CLAUDE.md 组合模板
+
+仅当团队主要使用 Claude Code 且需要 Claude 专属能力时添加。通用规则仍放 `AGENTS.md`。
+
+```markdown
+# CLAUDE.md
+
+@AGENTS.md
+
+## Claude Code 专属规则
+
+- 使用 hooks / commands / memory 的项目约定：<只写 Claude Code 独有内容>。
+- 个人本地偏好放 `CLAUDE.local.md`，不要提交。
+- 不要在这里重复 `AGENTS.md` 已有规则。
+```
+
+## 裁剪检查
+
+生成后逐条检查：
+
+| 检查项 | 处理 |
+| --- | --- |
+| 是否超过 120 行 | 下沉细节到深文档，只保留索引 |
+| 是否复制 README 项目介绍 | 删除，改为 README 链接 |
+| 是否包含通用编码常识 | 删除 |
+| 是否缺少代码地图入口 | 新增 `docs/ai/repo-map.md` 或说明为什么项目太小不需要 |
+| 是否把目录级规则堆在根 AGENTS.md | 下沉到最接近适用范围的子目录 `AGENTS.md` |
+| 是否没有说明 canonical | 补充模板源 / 活跃副本 / 运行时副本的优先级 |
+| 禁令是否没有替代方案 | 补替代方案或降级为风险 |
+| 是否引用不存在的命令或路径 | 修正或删除 |
+| 自动化可检查的内容是否只写文字 | 补充脚本 / hook / CI / verify 入口 |
+| 深文档是否无法从入口发现 | 加入索引 |