AI 的「最高指令」—— 所有需求分析、任务拆分、代码生成全部据此执行。决定了生成代码的技术栈、命名规范、错误码体系。
📄 .speccore/CONSTITUTION.md
✅ init 已自动检测：工程名、Git 仓库地址。其余字段可通过以下方式完善：
🤖 方式 1：AI 扫描工程代码（推荐）
AI 读取源码自动识别技术栈、框架、命名风格，直接写入。说不同的话，改不同的范围：
/spec-ask "分析代码，完善技术宪法" ← 只改宪法
/spec-ask "分析项目，完善所有配置" ← 宪法+团队+索引
/spec-ask "扫描代码，生成代码索引" ← 只建索引
✍️ 方式 2：手动编辑
打开文件按注释提示填写，只填必填项即可，其余按需补充
编辑 .speccore/CONSTITUTION.md
🔍 全局分析（了解现有项目推荐）
一句话扫描所有工程源码，自动生成技术栈、接口清单、数据模型等 8 类文档。适合接手新项目时快速摸清全貌：
/spec-ask "全局分析所有工程代码" ← 意图式
/spec-analyze --scope global ← 显式命令
--scope global — 全项目范围（非迭代级），在 AI 对话框中输入
📂 输出到 .speccore/GLOBAL/platforms/{端名}/，每端独立一套（TECH_STACK / API_INVENTORY / DATA_MODEL ...）
⏱ 与迭代分析不同：全局分析扫源码生成项目文档，迭代分析读需求生成技术规格（步骤 6 做的事）
✅项目信息表— 工程名 / 源码路径 / Git 仓库（init 已自动填写）
✅技术栈— 后端语言+框架、前端框架、数据库、缓存
✅命名规范— API 路径、错误码、数据库、代码命名风格
⬜异常码体系— 按模块定义错误码表（可选，按需补充）
⬜Git 分支策略— 默认分支、任务分支、保护分支规则（可选）
💡 作用：AI 生成代码时严格遵循这里的技术栈。例如写了 Spring Boot + MySQL，AI 就不会生成 NestJS + PostgreSQL 的代码。
📋 双配置系统（v8.3.25+）
除 CONSTITUTION.md 外，init 还自动生成了两个 YAML 配置文件，分别控制系统级和项目级行为：
⚙️ .speccore.yml — 系统配置
控制 CLI 运行时行为：质量门禁、AI 路由、自动化策略。所有字段已带中文注释，按需修改即可。
quality_gates / arbitration / settings / ask
🏗️ .speccore/PROJECT.yaml — 项目配置
定义工程列表、源码路径、Git 配置。init 时 platforms 为空，需手动添加你的后端/前端工程。
platforms / git / code_scope
💡 快速配置：用 AI 扫描代码自动填写 — /spec-ask "分析项目，完善所有配置"
填写团队成员和可用天数。AI 拆分任务时会根据团队规模自动调整粒度，一个端可以有多个负责人，作为拆分时的默认责任人参考（后期可手动修改）。
📄 Iteration-xxx/STAFFING.md（步骤 3 创建迭代后生成）
格式示例：
| 成员 | 角色 | 负责端 | 每周可用天数 |
| 张三 | 后端 | API 服务 | 5 |
| 李四 | 前端 | Web, H5 | 4 |
| 王五 | 全栈 | Admin | 3 |
💡 联动：≤3人 → 粗粒度拆分 | 4-8人 → 中粒度（默认）| >8人 → 细粒度拆分
迭代是一组需求的载体，包含需求文档、任务、代码等所有内容。先创建一个迭代，再把需求放进去。
📁 创建后生成的目录结构
Iteration-xxx/
├── 010-requirements/ ← 放需求文档的地方
├── 020-specs/ ← AI 分析后生成的技术规格
└── 030-tasks/ ← AI 拆分后的开发任务
speccore iteration create -n <迭代短名> --topic <中文描述>
-n <迭代短名> — 自定义英文名（如 login / Q1），后续命令用它引用
--topic <中文描述> — 迭代用途说明（如 "登录功能"）
💡 这是 CLI 命令，在终端中执行。创建后在下方步骤导入需求时用这个短名引用。
把产品需求放进步骤 3 创建的迭代中。推荐直接用自然语言描述，AI 会帮你整理成标准需求文档：
🤖 自然语言（推荐）
用口语描述需求 → AI 澄清 → 你确认 → 自动生成标准需求文档，支持反复修改
/spec-ask "新增用户登录功能"
📎 文件导入
把 Word / PDF / Markdown 文档交给 AI，自动提取需求并转换
/spec-ask "导入 PRD.docx 到 my-iter"
还有更多方式：📂 把文件丢到 .speccore/inbox/ 目录自动识别 | ✍️ 直接编辑迭代下 010-requirements/ 目录
💡 导入后，下一步 AI 分析会自动读取这些需求文档，生成 ANALYSIS.md、TECH.md 等 7 份技术规格。
以下内容按需补充，AI 在工作时会读取作为参考：
📐
PATTERNS/
代码模式模板
定义组件/服务/中间件的标准写法
📏
RULES/
代码审查规则
定义 Code Review 的检查项
🗺️
PROJECT/
项目全景文档
架构/团队/依赖关系
📄
templates/
用户自定义文档模板
覆盖或扩展 analyze 生成的规格风格
一切就绪，按以下流程推进开发：
需求分析→
任务拆分→
执行开发→
验证交付→
质量验证
📋 完整示例流程
# 1. 创建迭代（终端执行）
speccore iteration create -n login --topic "登录功能"
# 2. 分析需求（AI 对话框）
/spec-ask "分析 login 的需求"
# 3. 拆分任务（AI 对话框）
/spec-ask "拆分 login 的任务"
# 4. 执行开发（AI 对话框）
/spec-ask "开发 Task-001"
# 5. 质量验证（终端执行）
speccore verify -t Task-001 --ui
# 6. 提交归档（AI 对话框）
/spec-ask "完成 Task-001"
🤖 方式 A：意图式（推荐）
用自然语言告诉 AI，每步自动判断：
/spec-ask "分析 my-iter 的需求"
/spec-ask "拆分任务"
/spec-ask "开发 Task-001"
/spec-ask "完成 Task-001"
⌨️ 方式 B：显式命令（也在 AI 对话框中使用）
命令模板，将 <参数> 替换为你的实际值：
/spec-analyze -I <迭代名>
/spec-taskify -i <迭代名>
/spec-execute -t <任务名>
/spec-done -t <任务名>
-I <迭代名> — analyze 用大写 -I，其余用小写 -i
-t <任务名> — Task-001 / Task-002 ...
--prompt 已内置在 Skill 中，无需手动添加
💡 两种方式都在 AI 对话框中使用，可以混用。例如先用意图式分析，再用显式命令执行特定任务。
⚡ 自动化模式
🎯 三种执行模式（按需选择）
🔒 全程确认
每步展示结果，等你确认后再继续。适合首次使用。
/spec-ask "分析 my-iter 的需求"
⚡ 半自动
分析和拆分自动完成，执行开发前暂停。适合日常开发。
/spec-ask "分析 my-iter 并拆分任务"
🚀 全自动
一键跑完整个流水线，不中途暂停。适合熟悉后批量推进。
/spec-ask "全自动推进 my-iter"
💡 speccore run 是流水线入口：无参即智能续跑（检测断点从第一个未完成阶段继续），也可按预设流水线或起止点自动执行。快捷语法糖（v8.3.290+）：speccore run develop（preset 直呼）、speccore run smoke（单阶段快捷）、speccore run split-units to execute（阶段范围）——高频操作不必依赖 ask 引擎。
🧪 测试验证（v8.3.350+）
开发完成后用两条线保障质量——传统冒烟 + AI 视觉验证，按需选择：
🤖 AI 浏览器验证（无需写选择器）
CLI 从 UI_SPEC/TEST 切片生成自然语言剧本，宿主 AI 用 Browser 子代理真实打开页面逐项验证，截图+判定回写结果：
/spec-verify --ai
speccore verify --ai --scope deployed
👁️ 视觉判定兜底（只截图也能断言）
AI 仅截图未判定（judged=false）时，CLI 用视觉模型对「截图+预期结果原文」做业务断言，三级通道自动回退（Browser 子代理 → Playwright MCP → 视觉判定）：
speccore verify --ai-judge <results.json>
🔢 账号密码走环境变量
账号权威源：环境文件 tests.accounts（就近声明），accounts.yaml 为全局兑底；username/password 支持 ${VAR} 引用，密码不落盘不泄密：
password: ${STAGING_USER_PASSWORD}
💡 传统冒烟 依旧可用：speccore verify --config ./tests/smoke.yaml --stage dev，与 AI 验证互不干扰。
🎛️ 双线开关与剧本分层（settings.tests）
.speccore.yml 的 settings.tests 三段开关，缺省全开，按需关闭：
smoke.enabled: false — 关冒烟线（质量门禁自动触发的 UI 验证跳过）
ai_verify.enabled: false — 关 AI 验证线
layered.common / layered.modules: false — 关剧本某层（公共能力层/模块层，关闭不生成场景）
三条触发路径，显式优先于配置：CLI 显式参数（--ai / --ui，始终执行）＞ 配置开关（settings.tests，兜底）＞ 质量门禁自动触发（受开关拦截，可被显式参数覆盖）
📚 提示词库（快速上手）
内置常用操作模板，按场景分类（核心流程/迭代管理/分析文档/开发执行），复制即用：
speccore prompts
打开提示词库页面，浏览预设模板，点击复制自动带上 /spec-ask 前缀
🔍 分析需求
🧩 拆分任务
▶️ 执行任务
📊 查看进度
📖 重新查看本指南
本指南保存在 outputs/speccore-setup-guide.html，随时可在浏览器中打开查看。
也可以让 AI 重新展示：/spec-ask "打开配置引导"
❓ 常见问题
Q: 我怎么知道 CONSTITUTION.md 填对了？
A: 不用完美！init 已自动填写工程名和 Git 仓库。技术栈可以用 AI 扫描：/spec-ask "分析代码，完善技术宪法"。必填项只有技术栈（后端/前端/数据库），其他按需补充。
Q: 团队排期不填会怎样？
A: 不影响使用。AI 会用默认的中粒度拆分（4-8人规模）。后续需要时再编辑 Iteration-xxx/STAFFING.md 即可。
Q: 我能改迭代名吗？
A: 可以。用 speccore rename --iteration 旧名 新名 或在 AI 对话框说 /spec-ask "把迭代 old-name 重命名为 new-name"。
Q: 需求文档放哪？
A: 放到迭代目录下的 010-requirements/ 文件夹。或者直接用自然语言描述：/spec-ask "新增用户登录功能"，AI 会自动生成标准需求文档。