用途:FCIS 用于在编写或重构代码、创建文件前,强制把纯业务逻辑(Functional Core)与副作用(Imperative Shell)分离。纯函数集中在一个文件,I/O 操作集中在另一个文件。其理由是纯函数易于测试、无需 mock,I/O 被隔离在薄壳中,业务逻辑无副作用时缺陷在结构上更难出现。
主要能力与规则:
- Functional Core 只含纯函数(相同输入恒得相同输出)、业务逻辑、校验、计算、转换、数据结构操作;不得含文件 I/O、数据库操作、HTTP 请求、环境变量访问、Date.now()、Math.random() 等非确定性函数或函数作用域外的状态变更。日志是唯一允许的副作用,可传入 logger,单测时传 no-op logger。
- Imperative Shell 只含 I/O(文件系统、数据库、HTTP、环境)、编排(取数→调用 Core→持久化)、I/O 错误处理与最少业务逻辑;不得含复杂计算、业务规则校验或超出格式转换的数据变换。
- 代码流固定为 GATHER(Shell 取数)→ PROCESS(Core 纯处理)→ PERSIST(Shell 保存)。
- 强制文件分类:每个含运行时行为的文件必须加注释 // pattern: Functional Core、// pattern: Imperative Shell 或 // pattern: Mixed (needs refactoring)。确实无法分离时须写 // pattern: Mixed (unavoidable) 并附具体技术理由。
豁免文件:仅类型文件、常量/枚举类文件、barrel/index 重导出文件、测试文件、生成文件、Bash/shell 脚本、配置文件、Markdown、HTML、任务运行文件(justfile、Makefile)、包清单、数据文件。若豁免文件新增运行时逻辑,则须分类。
使用方式:写函数前先判断——能否不依赖外部环境运行?能则为 Functional Core;否则是否协调 I/O?是则为 Imperative Shell;若同时含业务逻辑与 I/O,应停止并重构或上报用户。重构模式包括:从非纯函数中抽取纯核心、用返回值替代原地修改、补充缺失的逆操作、用依赖注入替换硬编码依赖。重构优先级:抽取纯核心优先,其次补逆操作、返回值替代修改、注入依赖。
适用场景:编写任何新代码文件、重构既有代码、审查架构决策、判断逻辑归属,以及出现“这个函数该放哪”“给计算加数据库调用”“写测试需要复杂 mock”等信号时。
限制:资料未提供该技能的安装命令、平台支持、收费或价格信息,暂未提供。混合关注点即需重构;若无法分离,应携带具体技术理由上报用户,不应默认混合是必要的。