flatten-code-flow

name

flatten-code-flow

description

Review and refactor code toward flatter orchestration, atomic helper steps, and readable top-level workflows. Use when the user asks to clean up code smells, review implementation structure, reduce nested call chains, make an orchestrator function show the full business flow, reorder declarations by call order, split mixed-responsibility helpers, or apply ideas such as One-Hop Rule, flat call flow, atomic SRP, avoid relay orchestration, 函数调用链扁平化, 主流程平铺, 原子化步骤, 避免嵌套调用, 代码异味清理, or Review/重构 for readability.

扁平化代码流程

目标

使用这个 skill 时，要把实现逻辑整理到更容易阅读的形状，而不是做大而泛的重设计。优先让主控函数像目录大纲一样展示业务流程；子函数保持小而原子，每个名字只代表一个清晰步骤。

核心规则

把主控函数视为业务流程的真实入口。重要阶段应该按顺序出现在主控函数里，例如：

DuplicateReport report;
FileWalkResult walkResult = fileWalker_.collect_files(rootPath);
SizeBuckets filesBySize = group_files_by_size(walkResult.files);
std::vector<FileInfo> candidates = collect_hash_candidates(filesBySize);
std::vector<HashResult> hashResults = hash_candidates(candidates);
add_hash_results(hashResults, report);
sort_report(report);
return report;

遵循 One-Hop Rule：当某个阶段属于业务主流程时，不要把它藏进 A -> B -> C -> D 的深层调用链里。

避免接力编排：子步骤通常应该把结果返回给主控函数，而不是在内部直接调用下一个业务步骤。

保持步骤原子化：函数名只表达一个动作时，函数内部不要悄悄完成多个阶段，例如 read + parse + execute、group + filter + hash、chat + tool loop + persistence。

避免过度拆分：如果抽函数只是给一行显而易见的代码换个名字，或者让局部状态更难看清，就不要抽象。

Review 流程

1. 先画出当前流程。

   • 找到入口函数或主控函数。
   • 用自然语言写出真实调用链。
   • 标出哪些 helper 隐藏了重要阶段。

2. 对照读者心智模型。

   • 顶层函数是否回答了“下一步发生什么”？
   • helper 名字是否准确覆盖了真实职责？
   • README、测试或注释中明确出现的阶段，是否被代码藏在嵌套 helper 里？

3. 给发现分类。

   • 正确性风险：接口过期、构建目标失败、测试缺失、假设破裂。
   • 结构性异味：嵌套编排、职责混合、声明顺序妨碍阅读。
   • 风格偏好：没有明确理解收益的格式或命名调整。

4. 优先修高信号问题。

   • correctness 优先于纯整理。
   • 除非用户要求行为变化，否则保持行为不变。
   • 只修改完成当前清理所需的最小文件集合。

5. 验证。

   • 先跑与改动相关的 focused tests。
   • 如果成本低，再跑更大范围测试或相关 build target。
   • 明确说明没有验证到的部分。

重构模式

把隐藏阶段抬到主流程。比如从：

const std::vector<FileInfo> candidates = collect_hash_candidates(files);

改成：

const SizeBuckets filesBySize = group_files_by_size(files);
const std::vector<FileInfo> candidates = collect_hash_candidates(filesBySize);

只有当 group_files_by_size 是有意义的领域阶段，而不仅仅是低层实现细节时，才这样做。

收窄 helper 职责。比如让：

collect_hash_candidates(files)

从“按大小分组并挑出 hash 候选文件”，变成“从已经按大小分好的组里挑出 hash 候选文件”。

按阅读顺序排列声明：

SizeBuckets group_files_by_size(...) const;
std::vector<FileInfo> collect_hash_candidates(...) const;
std::vector<HashResult> hash_candidates(...) const;
void add_hash_results(...) const;
void add_duplicate_groups(...) const;
void sort_report(...) const;

如果函数声明依赖类型别名，先放类型别名。不要为了匹配 private 实现顺序而破坏 public API 的表达清晰度。

护栏

不要盲目扁平化所有调用。低层实现细节、校验 helper、小型转换、算法内部步骤，如果不是领域主流程，可以保留嵌套。

不要为了“看起来更整洁”新增 framework layer、interface、factory 或配置对象。

不要把不相关清理混进同一次改动。除非用户明确要求清理整个项目，并且改动仍然容易验证。

用户只要求 Review 时，先给判断和理由，不要直接改代码。用户要求修复时，实施最窄但完整的一组修改，并完成验证。

输出形状

分析型请求建议回答：

• proposed flattening 是否合理；
• 它解决了哪个具体调用流程问题；
• 附近是否存在更高优先级的 correctness issue；
• 下一步最安全的实施方式和验证命令。

实现型请求建议回答：

• 修改了哪些文件，以及结构效果是什么；
• 跑了哪些测试或构建；
• 是否避开了已有的 dirty worktree 或 staged changes。

资源

references/prompt.md 是用户原始笔记的归档拷贝，不属于默认工作流。只有当用户明确要求查看或引用原始笔记时，才读取它。