CLAUDE.md

本文件为在本仓库工作的 Claude Code 提供项目指南。请在动手前先阅读本文件与 docs/ 下相关文档。

一、项目是什么

问题画像与任务规格化平台（TaskSpec Studio）——面向 AI Agent 时代的"任务建模层"。它把人的模糊需求、历史案例、专家经验、业务规则和工具权限，转化为可执行、可验证、可审计、可持续优化的任务规格（TaskSpec），再驱动 Agent、工具、验证器和审批流协同工作。

一句话定位：

让 AI 系统先理解任务，再执行任务。

产品范式：人提出任务 → 系统生成任务画像 → TaskSpec 驱动执行 → 验证器检查 → 人类审批 → 反馈优化。

完整背景见根目录立项书 task_spec_studio_project_proposal.md，以及 docs/产品概述.md。

二、当前阶段

• 已落地首个薄切片应用代码：任务画像副驾驶（标书场景、mock 模型），位于仓库根的 Next.js 应用（app/、lib/、components/）。产品文档与 specs/ 资产仍是事实来源。
• 首个落地场景（MVP）：标书 / 项目建议书（见 docs/MVP范围.md）。
• 本地开发见 README.开发.md；切片设计与实现计划见 docs/开发/。

三、关键概念速览

• 任务规格（TaskSpec）：核心数据结构，13 段（目标/输入/约束/证据/工具/工作流/验证器/人机协作/输出/学习等）。详见 docs/TaskSpec规格.md。
• 任务画像（Problem Profiling）：从自然语言与材料中抽取任务目标、边界、证据、工具、验证、审批要求的过程。
• 三种产品形态：任务入口副驾驶（Task Intake Copilot）、TaskSpec 工作室（TaskSpec Studio）、任务运行时与治理层（Task Runtime & Governance Layer）。
• 验证器前置 + 人机协作分级：在画像阶段即定义验证规则；按风险（低/中/高/极高）决定自动执行/确认/审批/阻断。

术语统一以 docs/术语表.md 为准。

四、目录导航

.
├── CLAUDE.md                          # 本文件：给 Claude 的项目指南
├── README.md                          # 项目说明与导航
├── README.开发.md                     # 本地开发说明（启动 / 测试 / 构建）
├── task_spec_studio_project_proposal.md  # 原始立项书（事实来源，勿随意改动）
├── docs/                              # 产品与设计文档
│   ├── 产品概述.md                    # 定位、价值、形态、用户、场景、差异
│   ├── 术语表.md                      # 统一术语与中文译名、语言约定
│   ├── TaskSpec规格.md                # ★ 核心数据结构标准（schema + 字段说明）
│   ├── 架构设计.md                    # 六层架构、数据流、运行时八模块
│   ├── 产品设计原则.md                # 五条核心原则（决策"宪法"）
│   ├── MVP范围.md                     # 标书场景 MVP：流程、功能、验收、边界
│   ├── 实施路线图.md                  # 四阶段路径、成果、风险应对
│   ├── 关键指标.md                    # 使用/质量/业务/资产 四类指标
│   ├── 技能-task-spec.md              # task-spec 技能上手：何时用 / 怎么调 / 受控评估结论 / 局限
│   └── 开发/                          # 切片设计文档与实现计划（薄切片、验证器执行引擎…）
├── specs/                            # TaskSpec 资产库（10 个可执行规格样例，均为 v1 / 已发布）
│   ├── README.md                      # 资产库说明、命名约定与资产清单
│   ├── 标书响应.taskspec.yaml          # 场景一
│   ├── 客户投诉分析.taskspec.yaml      # 场景四 / 7.1
│   ├── 项目建议书.taskspec.yaml        # 4.1.2
│   ├── 经营复盘.taskspec.yaml          # 场景二
│   ├── 合同审查.taskspec.yaml          # 场景三
│   ├── 供应商评估.taskspec.yaml        # 资产清单
│   ├── 政策解读.taskspec.yaml          # 资产清单
│   ├── 竞品分析.taskspec.yaml          # 资产清单
│   ├── 研发周报.taskspec.yaml          # 资产清单
│   ├── 高管汇报.taskspec.yaml          # 资产清单
│   ├── generated/                     # 「另存」生成的 TaskSpec（.gitignore 忽略）
│   └── traces/                        # 「保存轨迹」生成的执行轨迹（.gitignore 忽略）
│
├── app/                              # Next.js 应用：page.tsx + api/{profile,taskspec,save,validate,produce,trace,clarify,workflow}/route.ts
├── lib/
│   ├── taskspec/                      # schema / profile-schema / to-yaml（数据契约）
│   ├── ai/                            # provider 抽象 + mock-data（含 buildMockDraft）+ deepseek-provider（含 reviewDefinition 定义质量语义复判）
│   ├── validators/                    # 验证器引擎（规格层/产物层）+ 目标可判定性检查 + 定义质量诊断（diagnoseDefinition + 清晰度分）+ 澄清并回（applyClarifications）+ 终止策略（judgeClarifyConvergence：达标/无提升/轮次上限）+ 内容验证器（条款完整性 / 超授权风险）+ 成功标准核验（compileCriteriaChecks + criteriaChecker：逐条对产物判定+证据）+ 规格门禁（spec-gate：发布门禁——已发布须无定义体占位/清晰度达标/定稿门控通过；优先级口径——排序加权字样须有可计算口径；自洽性——无悬空引用(§章节/见上文/Move)；奖励诚实，草稿带占位放行）+ 消费侧复算门（acceptance.verifyForAcceptance：从内容现推是否可接受、不信任 status 自报；MCP 工具与 app 消费边界同一逻辑源）+ 任务链健全度诊断（workflow-linter + diagnoseWorkflow：结构 DAG/完备/归属/覆盖/顺序，独立健全度分）+ 模型复判接入点
│   ├── trace/                         # 执行轨迹类型与纯函数（recordEvent / eventTitle）
│   └── eval/                          # 清晰度分效度护栏（配对退化 degradeSpec → 盲执行对作者意图命中率 judgeCorrectness → 回归地板；npm run eval:clarity，详见 eval/README.md）
├── components/intake/                # 五步向导：输入→画像→TaskSpec→目标校验与澄清闭环（诊断→答→复检）→产物校验与人工处置 + 任务链健全度面板 + 执行轨迹时间线（wizard-reducer + IntakeWizard）
├── __tests__/                        # Vitest 单元 / 集成测试
├── mcp/                              # taskspec-engine MCP server：把 lib/validators 确定性函数暴露为工具(tools.ts + server.ts，stdio)；强制在消费侧复算(verify_for_acceptance)；启动 npm run mcp，注册见 .mcp.json / mcp/README.md
├── .claude/skills/task-spec/         # 方法论沉淀的可复用技能（SKILL.md + references/）；显式调用，含可安装包 task-spec.skill；用法见 docs/技能-task-spec.md
└── package.json · tsconfig.json · next.config.mjs · tailwind/postcss/vitest 配置

开发（任务画像副驾驶薄切片）

• 技术栈：Next.js + TypeScript + Tailwind + Zod + yaml；测试 Vitest。
• 启动：npm install && npm run dev；测试：npm run test。
• 模型：默认 mock（AI_PROVIDER=mock）；可选 DeepSeek（设 AI_PROVIDER=deepseek 并在 .env.local 配 DEEPSEEK_API_KEY），实现见 lib/ai/deepseek-provider.ts。
• 设计与计划见 docs/开发/。

五、写作与产出约定（重要）

本项目硬性要求：所有生成的交付物（artifacts）默认使用简体中文，非必要不使用英文。

允许保留英文的"必要例外"仅限：

1. 产品名与核心概念：TaskSpec Studio、TaskSpec（首次出现写成"任务规格（TaskSpec）"）。
2. TaskSpec schema 的字段键名（task_name、goal、constraints 等）：保留英文，作为机器可读、跨系统稳定引用的标准；文档与样例中始终配中文译名/注释。不要翻译或改动键名。
3. 个别业界术语（LLM-as-judge、Human-in-the-loop、RPA、prompt chaining 等）：首次出现给中文解释并括注英文，之后用中文。

其余正文、标题、表格、列表、注释、提交信息一律中文。

其他约定：

• Markdown 文件以一个一级标题（#）开头，层级清晰，表格用中文表头，结构图/代码用代码块（标 text 或 yaml）。
• 文风专业、准确、结构化，避免空话与营销腔；多用条目、表格、示例。
• 忠实于立项书：不杜撰立项书之外的事实、数字或承诺；合理归纳与建议须明确标注为"建议"。

六、TaskSpec 编写约定

• 文件命名：<场景>.taskspec.yaml，放在 specs/。
• 结构遵循 docs/TaskSpec规格.md 的 13 段；键名英文、取值中文、关键处加中文注释。
• 顶部建议补充元字段：version / status（草稿/评审中/已发布/已归档）/ owner / updated_at。
• TaskSpec 是活文档：执行反馈、人工修改、失败案例回流到 learning 段并驱动版本迭代。

七、协作与提交约定

• 提交信息用中文，简明说明改动（例如"新增合同审查 TaskSpec 样例"）。
• 修改文档时保持术语与 docs/术语表.md 一致；新增术语先在术语表登记。
• 不随意改动 task_spec_studio_project_proposal.md（它是事实来源）。
• 涉及创建新文档时，更新本文件第四节"目录导航"与 README.md 的索引。

八、暂不做的事（项目边界）

• 不直接定位为通用聊天机器人；
• 不以 prompt 模板库作为核心产品；
• 不做纯低代码 workflow 平台；
• 不追求所有任务完全自动化；
• 不替代专家最终责任；
• 不在高风险场景中直接给出不可审查的自动决策。