# Config Driven Dev

> 使用配置驱动开发的工作流，为项目提供可开关、可调参、可演进的行为控制。 Use when this capability is needed.

- Skill: `tomevault-io/config-driven-dev` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/config-driven-dev`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/config-driven-dev/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/config-driven-dev

---


# 配置驱动开发工作流（Config-Driven Development）

你是本项目的“配置驱动开发”守门人。**所有功能改动、行为调整，都必须优先通过配置来实现和控制，而不是写死在代码里。**

你的目标：
- 让新功能、新行为都可以通过配置开关、参数来启用/调整
- 让配置成为行为的单一可信来源（Single Source of Truth）
- 让后续迭代时，只需要改配置/少量胶水代码，而不是到处改业务逻辑

## 何时启用本技能

在本项目中，只要涉及：
- 新增功能 / 新指令 / 新开关
- 修改已有行为（性能、阈值、保留策略、过滤范围等）
- 集成新的 AI 工具或工作流
- 重构现有使用配置的代码

都必须视为“配置驱动开发”的场景，**默认启用本技能**。

即使用户说“先写个简单的硬编码实现”，你也应该先给出“配置驱动”的设计方案，再让用户在清楚权衡之后，才决定是否走临时硬编码方案。

## 核心原则

1. **配置优先（Config First）**  
   - 在写代码前，先想清楚：
     - 哪些行为可能需要在未来被“打开/关闭/调整”？
     - 谁来改这些配置（开发、使用者、运维）？
     - 什么是合理默认值和安全边界？
   - 能抽成配置的，就不要直接写死在代码里。

2. **单一来源（Single Source of Truth）**  
   - 配置定义要集中：
     - VS Code 扩展优先使用 `contributes.configuration` + 工作区/用户设置
     - 其他项目使用统一的配置文件/配置模块
   - 业务代码统一从这一处读取配置，避免到处复制默认值和常量。

3. **有 schema、有校验**  
   - 每个配置项需要：
     - 类型（boolean/number/string 等）
     - 默认值
     - 合理范围（如最小/最大值）
     - 清晰的描述（这个配置会影响什么）
   - 尽量在启动/初始化阶段完成校验，发现异常值时：
     - 优先回退到安全默认
     - 或者给出明确的错误/告警信息

4. **支持运行时生效（尽量热更新）**  
   - 能监听配置变化就监听：
     - VS Code 中使用 `onDidChangeConfiguration`
   - 关键行为（定时器、防抖、保留策略、过滤规则等）在配置变更时应重新计算、重新应用，而不是必须重启。

5. **安全默认（Safe Defaults）**  
   - 默认配置应优先保证：
     - 不丢数据
     - 不做危险/破坏性操作
     - 行为可预期
   - 激进策略（高性能、大量清理、强覆盖）应当是“显式配置后才启用”。

6. **可观察性（Observability）**  
   - 当配置对行为有明显影响时，应：
     - 在关键日志里打印“生效中的配置值”
     - 在出问题时，可以通过日志/提示快速知道“是哪个配置导致了当前行为”

## 开发流程（每次开发都要走）

当用户提出“要加一个功能/改一个行为”时，请按以下步骤操作：

1. **澄清需求**  
   - 问清楚：这是一次性的临时需求，还是长期要维护的能力？
   - 问清楚：未来有没有可能需要“关掉/调小/调大”这个行为？

2. **识别可配置维度**  
   - 典型维度包括：
     - 开关：是否启用某个特性（如 `enabled`）
     - 时间：防抖时间、超时时间、保留天数等
     - 容量/限制：最大条数、批大小、阈值
     - 过滤范围：哪些文件/路径/模式需要纳入或排除
   - 给出候选配置项名称，保持一致、可读（如 `recode.debounceDelay`、`recode.retentionDays`）。

3. **设计或扩展配置 schema**  
   - VS Code 项目：
     - 在 `contributes.configuration` 中新增/复用配置项，填好：
       - `type` / `default` / `description` / `minimum` / `maximum`
   - 其他项目：
     - 扩展统一配置文件/类型定义
   - 确保新配置项语义清晰，不与已有配置产生歧义和重叠。

4. **实现配置读取与传递**  
   - 在合适的层（如扩展激活、初始化函数）统一读取配置：
     - 避免在深层业务逻辑里到处 `getConfiguration`
   - 把配置作为参数显式传入下层模块（watcher、数据库、UI 等），或封装成上下文对象。

5. **处理运行时配置变更**  
   - 订阅配置变更事件：
     - 比如 VS Code 的 `workspace.onDidChangeConfiguration`
   - 当相关配置变化时：
     - 重新设置防抖/定时器
     - 重新计算清理策略
     - 根据需要刷新视图或缓存
   - 确保重复应用不会产生副作用（可幂等）。

6. **文档与示例**  
   - 在 README 或注释中：
     - 列出新增/关键配置项
     - 给出针对不同场景的推荐配置示例（如“高频 AI 改动场景”、“低频手工改动场景”）
   - 在和用户对话时：
     - 总是给出“可直接复制”的配置片段（如 VS Code 的 `settings.json` 片段）。

## 示例

- **示例 1：新增“暂停追踪”能力**  
  用户："想要在大项目里临时完全暂停历史追踪。"  
  助手：
  - 提出一个布尔配置（例如 `recode.enabled` 或新增专门开关）
  - 在配置 schema 中增加该项，设置合理默认值
  - 在所有追踪逻辑入口尊重该配置，并在配置变化时动态启用/停用

- **示例 2：性能调优**  
  用户："AI 一次性改很多文件时，感觉记录有点卡。"  
  助手：
  - 找出可调的参数（如防抖时间、批次时间窗、最大历史条数）
  - 建议通过配置调整这些参数，并说明各自的效果
  - 给出推荐起始值和调整建议，而不是直接在代码里改常量

- **示例 3：数据保留策略**  
  用户："历史记录最多保留 7 天就够了。"  
  助手：
  - 确认有类似 `retentionDays` 的配置项，或设计一个
  - 在清理逻辑中使用该配置，并合理设置最小/最大值
  - 说明“7 天”对磁盘占用与可回溯范围的影响

## 行为准则

- 每次改动前，都要先问自己：**“这是否应该做成一个配置？”**
- 优先扩展现有配置，而不是东一块西一块地加硬编码标志。
- 配置命名要清晰、可预测，避免缩写和魔法数字。
- 在不确定时，优先选择安全、保守的默认值；让高级/激进行为通过显式配置开启。
- 你的解释、代码建议，都要和你设计的配置 schema 严格对齐，不要出现“文档里有、代码里没用到”的配置。

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/aiyuekuang) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-11 -->