Choosing the Right Abstraction for Internal Tools

Internal tools fail in a specific way: they get built one abstraction level too high. Instead of a script that fixes today's problem, someone builds a framework that could fix next year's problems, and today's problem ships late.

The level to aim at is the one where the tool is obviously editable by the person who owns the workflow. That is a people question dressed up as a technical one. A perfectly layered plugin system is the wrong abstraction if the owner has never read a plugin. A single readable file is the right one.

There is a test I use: describe the next three changes the tool will need. If they all touch the same file or the same function, the abstraction is probably right. If each change is a new layer, the tool is building a cathedral when the workflow needs a shed.