From 542a06907ce543fd8600b24eb93a07b8c84bdf04 Mon Sep 17 00:00:00 2001 From: tangweijie <877588133@qq.com> Date: Tue, 17 Mar 2026 10:43:00 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=A2=9E=E5=8A=A0=20TAPD=20=E5=8D=8F?= =?UTF-8?q?=E4=BD=9C=E7=BA=A6=E5=AE=9A=E4=B8=8E=E9=A1=B9=E7=9B=AE=E7=BB=91?= =?UTF-8?q?=E5=AE=9A?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 为仓库补充 TAPD 本地协作入口，固化默认 workspace、查询范围与输出模板，便于后续按统一口径开展需求与任务跟踪。 Co-Authored-By: Claude Sonnet 4.6 --- .tapd/.gitignore | 4 ++ .tapd/cache.md | 22 +++++++ .tapd/index.md | 45 +++++++++++++++ .tapd/templates.md | 140 +++++++++++++++++++++++++++++++++++++++++++++ CLAUDE.md | 15 +++++ 5 files changed, 226 insertions(+) create mode 100644 .tapd/.gitignore create mode 100644 .tapd/cache.md create mode 100644 .tapd/index.md create mode 100644 .tapd/templates.md diff --git a/.tapd/.gitignore b/.tapd/.gitignore new file mode 100644 index 0000000..dafdb4f --- /dev/null +++ b/.tapd/.gitignore @@ -0,0 +1,4 @@ +# TAPD local state +state.json +session.json +*.local.* diff --git a/.tapd/cache.md b/.tapd/cache.md new file mode 100644 index 0000000..5fb66b4 --- /dev/null +++ b/.tapd/cache.md @@ -0,0 +1,22 @@ +# TAPD 项目缓存 + +## Workspace Snapshot + +- workspace_id：`64404594` +- 项目名称：`水务数智营收管理系统` +- 类别：`project` +- 状态：`normal` +- 创建人：`朱艳贞_` +- 创建时间：`2025-04-15 17:38:26` +- company_id：`21531661` + +## 本地判定 + +- 本机 TAPD MCP：已可调用 +- 当前仓库：git 仓库 +- 当前项目已建立 `.tapd/` 目录结构 + +## 共享建议 + +本文件当前只保存稳定、可共享的项目缓存信息，可提交到仓库。 +如后续出现强本地化内容，应迁移到本地状态文件并通过 `.tapd/.gitignore` 忽略。 diff --git a/.tapd/index.md b/.tapd/index.md new file mode 100644 index 0000000..ac6f96b --- /dev/null +++ b/.tapd/index.md @@ -0,0 +1,45 @@ +# TAPD 项目索引 + +## Project Binding + +- 默认 workspace_id：`64404594` +- 默认项目名称：`水务数智营收管理系统` +- 当前仓库绑定策略：`锁定单项目` +- 默认对象范围：`story`、`task` +- 输出风格：`规范文档型` + +## 使用入口 + +当任务涉及 TAPD 项目、需求、缺陷、任务、迭代时，优先读取本文件。 + +如需补充项目缓存、术语口径、常用模板，再继续读取： + +- `./cache.md` +- `./templates.md` + +## 查询约定 + +- 当前仓库默认查询项目为 `64404594` +- 未经用户明确要求，不切换到其他 workspace +- 当前默认工作重心为：需求拆解与开发任务推进 +- 若任务转向缺陷跟踪或迭代汇报，应在输出中显式说明已切换对象范围 + +## 输出约定 + +- 输出语言默认使用中文 +- 优先给出结构化结论、对象编号、状态、负责人、时间等关键信息 +- 面向文档仓库时，优先采用可归档、可引用的规范化表达 +- 不在仓库文件中记录 token、Cookie、密码等敏感信息 + +## 粒度对齐约定 + +- TAPD 中的 `Story` 视为一个可独立评审、可独立交付、可独立验收的需求单元。 +- `Story` 是当前仓库与 `speckit` 对齐时的最小需求粒度，对应一个独立的 feature / `spec.md`。 +- TAPD 中的 `Task` 视为执行项，对应 `speckit.tasks` 中的具体任务，不单独作为 feature。 +- 若一个事项需要同步修改两篇及以上主文档，或同时涉及详细设计、接口设计、数据库设计中的两类及以上内容，应优先视为一个独立 `Story` / speckit feature。 +- 若一个事项仅涉及单个字段、单个表格、单处标题或单篇文档中的局部修订，默认按 `Task` 处理，而不是单独立项为 `Story`。 + +## 待补充项 + +- 常用术语字段排序可按后续使用习惯继续细化 +- 如后续需要周迭代汇报，可在 `templates.md` 中补充周报模板 diff --git a/.tapd/templates.md b/.tapd/templates.md new file mode 100644 index 0000000..119073f --- /dev/null +++ b/.tapd/templates.md @@ -0,0 +1,140 @@ +# TAPD 输出模板 + +## 1. 规范文档型：需求/任务查询结果 + +### 输出模板 + +- 项目：`{{workspace_name}}`（`{{workspace_id}}`） +- 对象类型：`{{entity_type}}` +- 查询条件：`{{query_summary}}` +- 结果摘要：`{{summary}}` + +#### 明细 + +| 编号 | 标题 | 状态 | 负责人 | 计划时间 | 备注 | +|------|------|------|--------|----------|------| +| {{id}} | {{name}} | {{status}} | {{owner}} | {{schedule}} | {{note}} | + +#### 结论 + +- 当前结论：{{conclusion}} +- 后续动作：{{next_action}} + +## 2. 规范文档型：缺陷跟踪结果 + +### 输出模板 + +- 项目：`{{workspace_name}}`（`{{workspace_id}}`） +- 缺陷范围：`{{query_summary}}` +- 结果摘要：`{{summary}}` + +| 缺陷ID | 标题 | 状态 | 严重程度 | 处理人 | 备注 | +|--------|------|------|----------|--------|------| +| {{id}} | {{title}} | {{status}} | {{severity}} | {{owner}} | {{note}} | + +## 3. 规范文档型：迭代汇报 + +### 输出模板 + +- 项目：`{{workspace_name}}`（`{{workspace_id}}`） +- 迭代：`{{iteration_name}}` +- 时间范围：`{{date_range}}` + +#### 进展概览 + +- 已完成：{{done_summary}} +- 进行中：{{progressing_summary}} +- 风险项：{{risk_summary}} + +#### 建议关注 + +- {{focus_1}} +- {{focus_2}} +- {{focus_3}} + +## 4. 粒度映射模板 + +### TAPD 与 speckit 对齐关系 + +| TAPD 层级 | speckit 对应物 | 说明 | +|-----------|----------------|------| +| Epic / 大主题 | feature 背景 | 例如 REV-005 这类主题范围 | +| Story | `spec.md` | 最小需求粒度，一个可独立评审与交付的设计闭环 | +| Task | `tasks.md` 中的任务项 | 具体执行动作，如修改某篇文档、补某张表、校核某组引用 | + +### 立项判断规则 + +优先作为一个独立 Story / speckit feature 的情形： + +- 需要跨两篇及以上主文档协同修改 +- 需要同时对齐详细设计、接口设计、数据库设计中的两类及以上内容 +- 具备明确边界、验收标准与独立评审价值 + +优先作为 Task 的情形： + +- 单字段修订 +- 单表格补充 +- 单文档局部改写 +- 链接、标题、编号等局部一致性修复 + +### speckit feature 命名模板 + +#### 推荐命名公式 + +`<主题编号>-<场景关键词>-<交付动作>` + +#### 推荐写法 + +- `rev005-invoice-apply-design` +- `rev005-invoice-redflush-alignment` +- `rev005-invoice-status-rules` +- `rev005-invoice-db-interface-sync` + +#### 中文标题模板 + +`<主题编号>：<业务场景><交付动作>` + +示例： + +- `REV-005：补齐发票开具申请设计闭环` +- `REV-005：统一发票红冲字段口径` +- `REV-005：补齐发票状态流转规则` + +#### 命名约束 + +- 使用小写英文与连字符 `-` +- 不使用空格、中文、下划线 +- 主题编号放在最前面，便于同批需求聚类 +- 场景关键词优先写业务对象，不要只写模块名 +- 交付动作优先使用 `design`、`alignment`、`rules`、`sync`、`cleanup` 等可辨识词 +- 一个 feature 名称只表达一个独立交付目标，不混入多个并列场景 + +#### 交付动作建议词表 + +- `design`：补齐某业务场景设计闭环 +- `alignment`：统一多文档之间的字段或口径 +- `rules`：补齐规则、状态流转、约束条件 +- `sync`：做跨文档同步与一致性收口 +- `cleanup`：处理遗留结构、引用、编号、术语收口 + +#### 快速套用模板 + +- 场景设计类：`--design` +- 口径统一类：`--alignment` +- 规则补齐类：`--rules` +- 跨文档收口类：`--sync` + +#### 当前仓库推荐示例 + +- `rev005-invoice-apply-design` +- `rev005-invoice-issue-result-sync` +- `rev005-invoice-redflush-alignment` +- `rev005-invoice-status-rules` +- `rev005-invoice-db-interface-sync` + +## 术语偏好 + +- story：需求 +- task：任务 +- bug：缺陷 +- iteration：迭代 diff --git a/CLAUDE.md b/CLAUDE.md index 1c406dc..737f187 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -272,3 +272,18 @@ make unified-export - 可追溯到来源资料 - 满足甲方交付语境 - 便于后续继续维护、评审与导出 + +## TAPD 协作约定 + +当任务涉及 TAPD 项目、需求、缺陷、任务、迭代时，优先读取仓库根目录 `.tapd/index.md`。 + +`.tapd/index.md` 作为当前仓库的 TAPD 绑定与使用入口；如需项目缓存、术语口径或输出模板，再继续读取： + +- `.tapd/cache.md` +- `.tapd/templates.md` + +当前仓库默认绑定 TAPD 项目 `64404594`（`水务数智营收管理系统`），并按单项目方式使用；如用户未明确要求，不切换到其他 workspace。 + +默认关注对象范围为需求（story）与任务（task），输出风格采用规范文档型，要求结果可归档、可引用、可直接纳入文档协作语境。 + +不得将 token、Cookie、密码或其他敏感凭据写入 `.tapd/` 或仓库文档。