agentleFS
JohnnyQ-commitsJohnnyQ-commits/aqueduct-data-agent/.claude/skills/change-management/SKILL.md

change-management

Skill2 starsChanged 32 days agoMITView on GitHub

需求变更管理技能。管理数据开发交付后的需求变更,确保变更可追溯、可审查、可回滚。 DO trigger when 业务方提出新增字段、修改逻辑、删除字段等需求变更, 用户提及"变更"、"新增字段"、"改逻辑"、"加指标"、"需求变了"、"CR"等关键词, 或对比新旧需求文档发现差异时。 Do NOT trigger for 首次开发(使用 data-developer)、仅审查已有SQL(使用审查模式)。

  • Deletes or force-pushes

15 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use andreessen, business-investment-advisor and 10 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • Hussain-ElfalahSkill

    andreessen

    Also in 4 projects that use this

  • Hussain-ElfalahSkill

    business-investment-advisor

    Also in 4 projects that use this

  • csiddhant796-blipSkill

    karpathy-coder

    Use when writing, reviewing, or committing code to enforce Karpathy's 4 coding principles — surface assumptions before coding, keep it simple, make surgical changes, define verifiable goals. Triggers on "review my diff", "check complexity", "am I overcomplicating this", "karpathy check", "before I commit", or any code quality concern where the LLM might be overcoding.

    Also in 4 projects that use this

  • csiddhant796-blipSkill

    self-eval

    Honestly evaluate AI work quality using a two-axis scoring system. Use after completing a task, code review, or work session to get an unbiased assessment. Detects score inflation, forces devil's advocate reasoning, and persists scores across sessions.

    Also in 4 projects that use this

  • +8 more from Hussain-Elfalah

The file

Files
SKILL.md

需求变更管理技能 (Requirement Change Management Skill)

用于管理数据开发过程中的需求变更,确保变更可追溯、可审查、可回滚。

参考文档

  • 变更流程详细参考 — 6 阶段工作流、变更类型、回归验证清单

Context

本技能用于需求已交付后的变更管理场景。当业务方提出新增字段、修改逻辑、删除字段等变更时, 必须通过标准化的 CR(Change Request)流程进行管理,确保:

  • 每次变更有独立目录和完整文档链
  • 变更 SQL 经过影响分析 + 回归验证后才能合并
  • 所有变更记录持久化保存,支持事后回溯

Instructions

执行变更管理 6 阶段流程:

Phase 1: 变更识别 (Change Identification)

  1. 读取新需求文档,与原始需求文档逐字段对比
  2. 识别:新增字段、修改字段、删除字段、逻辑变更
  3. 新业务表述检索:变更引入新指标/口径(业务表述)时,运行 python src/aqueduct/memory/history.py "<业务表述>" 检索全库历史命中——已有实现直接对齐其表.字段口径复用,禁止重复实现
  4. 输出:变更字段清单 + 逻辑差异说明

Phase 2: 变更需求文档

在 output/{需求名}/changes/CR-{NNN}_{简称}/ 下创建 Phase2-变更需求.md:

章节内容
基本信息CR编号、日期、需求编号、变更类型
新增字段清单字段名(英文/中文)、类型、所属模块
字段逻辑详情每个新字段的取数逻辑、计算公式
标签分档规则标签值定义、区间划分
影响分析新增/修改TMP表、修改ADS表、数据源变化
待确认问题需要业务方确认的歧义点

Phase 3: 变更 SQL

创建 Phase3-变更SQL.sql:

  1. 修改的TMP表:DROP + CREATE 完整重建
  2. 新增的TMP表:DROP + CREATE
  3. 修改的ADS表:追加字段的 SELECT 片段 + 追加 JOIN 片段
  4. 重跑顺序:明确列出需要重跑的表及顺序

规范:

  • 变更SQL必须可独立执行
  • 新增TMP命名:tmp_{库名}.tmp_{需求编号}_{主题}
  • 变更字段注释:-- [CR-NNN] 字段说明

Phase 4: 变更审查

创建 Phase4-变更审查报告.md:

审查维度检查项
逻辑正确性新增字段逻辑是否符合需求定义
回归风险已有字段是否受影响、JOIN是否膨胀
性能影响新增扫描量、新增JOIN数量
数据一致性新增字段与已有字段的交叉验证
V8 编译实测(新片段)变更新增/改动的 SQL 片段是否通过编译验证——按数据验证 Checklist 第〇节能力分级:L2/L1 在可执行通道实测编译(命令示例见 data-developer skill《平台通道适配映射》第二节),L0 降级静态自检并逐段标注"未编译";每个"编译通过"须附执行证据,无证据标 ⏳ 未实测
待确认问题标记已确认/未确认状态

审查结论:

  • ✅ 通过 — 可执行
  • ⚠️ 条件通过 — 待确认问题后可执行
  • ❌ 不通过 — 需修改后重新审查

Phase 5: 合并执行

  1. 合并变更SQL到主ETL SQL
  2. 更新DDL表结构
  3. 追加DQC测试用例
  4. 同步更新 Design.md、知识沉淀.md
  5. 按重跑顺序执行,运行回归验证

Phase 6: 归档

  1. 更新交付总报告(追加变更记录)
  2. 更新提效看板
  3. 更新语义模型(如有新实体变更)

Input Schema

VariableTypeDescription
requirement_namestring原始需求名称(用于定位 output 目录)
original_requirementstring原始需求文档路径或内容
new_requirementstring新需求文档路径或内容
change_descriptionstring变更描述(可选,人工补充)

Output Schema

output/{需求名}/changes/
├── CR-{NNN}_{简称}/
│   ├── Phase2-变更需求.md          ← Phase 2 产出
│   ├── Phase3-变更SQL.sql          ← Phase 3 产出
│   └── Phase4-变更审查报告.md      ← Phase 4 产出

Constraints

  • 每次变更必须创建独立 CR 目录,禁止直接修改主 SQL
  • 变更SQL必须经过审查后才能合并到主 SQL
  • 变更字段必须用 -- [CR-NNN] 注释标记来源
  • 合并后必须执行回归验证清单(5 项)
  • 所有变更记录必须持久化保存,不可删除

变更编号规则

CR-{三位序号}_{变更简称}
示例: CR-001_电商网点效能指标
      CR-002_新增客户分层标签
      CR-003_修复杂收占比逻辑

序号在 output/{需求名}/changes/ 目录下递增。

变更类型分类

类型说明影响范围示例
新增字段添加新的计算字段新增TMP+修改ADS效能指标、城市字段
逻辑修改修改已有字段的计算逻辑修改TMP+修改ADS修改标签区间
删除字段移除不再需要的字段修改ADS SELECT废弃指标
数据源变更更换或新增数据源可能影响多个TMP切换维表
架构调整TMP表拆分/合并重构TMP层新增DWS层

回归验证清单

#验证项SQL模板
1主键唯一性不变select count(*)=count(distinct pk) from {ADS表}
2已有字段值不变对比变更前后原有字段值
3新增字段非空率select count({新字段})/count(*) from {ADS表}
4新增字段枚举值select distinct {标签字段} from {ADS表}
5数据行数不变select count(*) from {ADS表}

与其他技能的关系

data-developer (首次开发)
    ↓ 交付后
change-management (本技能, 后续变更)
    ↓ 变更审查
data-developer Phase 4.5 (代码审查模式)

Examples

场景:业务方要求在已有的"业务效能报表"中新增"电商网点效能"指标

Phase 1 输出:

### 变更识别结果

| 变更项 | 类型 | 说明 |
|--------|------|------|
| 电商网点效能指标 | 新增字段 | 新增计算字段,需新建TMP表 |
| 城市维度 | 无变更 | 已有字段,不受影响 |

Phase 3 输出(变更SQL.sql):

-- ============================================================
-- CR-001_电商网点效能指标
-- 变更类型: 新增字段
-- 日期: 2026-06-10
-- ============================================================

-- 1. 新增TMP表: 电商网点效能明细
DROP TABLE IF EXISTS tmp_dwd.tmp_sample_business_efficiency;
CREATE TABLE tmp_dwd.tmp_sample_business_efficiency AS
SELECT
    emp_code,
    -- [CR-001] 电商网点效能指标
    COUNT(CASE WHEN order_type = 'ecommerce' THEN 1 END) as ecommerce_order_cnt,
    SUM(CASE WHEN order_type = 'ecommerce' THEN amount END) as ecommerce_amount
FROM dwd.order_detail
WHERE inc_day = '${bizdate}'
GROUP BY emp_code;

-- 2. 修改ADS表: 追加字段
-- 在 SELECT 中追加:
--   t_ecom.ecommerce_order_cnt,  -- [CR-001] 电商网点订单数
--   t_ecom.ecommerce_amount      -- [CR-001] 电商网点金额
-- 追加 JOIN:
--   LEFT JOIN tmp_dwd.tmp_sample_business_efficiency t_ecom
--     ON t_main.emp_code = t_ecom.emp_code

-- 3. 重跑顺序:
--   1) tmp_dwd.tmp_sample_business_efficiency
--   2) ads.ads_sample_business_report

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.