Build Disciplined Engineering and Efficient Validation Workflows for Coding Agents with lean-mode

What Is lean-mode?

lean-mode is a SKILL.md for coding Agents. Its goal is not to minimize code at all costs, but to give Agents clear criteria for answering two engineering questions:

1. Whether seemingly safe code is worth writing, such as validation, try/catch, abstraction layers, fallback logic, or additional safety subsystems.
2. Why the current build and test process is slow, and how to shorten inefficient validation loops to a reasonable duration.

The skill file is located at skills/lean-mode/SKILL.md and uses standard frontmatter: name, description, and a Markdown body. It does not depend on a specific host and can be used by any Agent that supports the SKILL.md convention.

The Core Problems It Addresses

During long coding sessions, models tend to develop two systematic behaviors: overly defensive programming and inefficient validation loops.

Overly Defensive Programming

Common examples include repeatedly performing null checks on trusted internal data, using exception handling to hide root causes, prematurely creating abstractions for a single implementation, and continually adding fallbacks without first identifying the source of a problem. Although the code may appear “safer,” it can increase maintenance costs and turn clear failures into error values that are difficult to trace.

Inefficient Validation Loops

Common examples include frequently running full builds, repeatedly using clean, disabling persistent processes, running every test each time, and waiting too long for commands that are clearly stuck. lean-mode constrains these behaviors through six categories of rules: process reuse, incremental execution, scope control, execution order, invocation frequency, and timeout management.

The quantitative data in the README comes from a single long session involving a Java and Gradle project of approximately 20k lines. It only demonstrates that the problem exists and should not be treated as an industry benchmark across models or projects.

Key Capabilities

• Validate once at the trust boundary:Requires first answering “Where does this null come from?” to avoid repeatedly checking trusted data after it has entered the system.
• Avoid swallowing root causes:Warns against returning null, false, an empty collection, or a zero value after a catch, because doing so may convert a clear exception into a harder-to-locate error.
• Constrain premature abstraction:An abstraction with only one implementation, created solely for possible future replacement, may not constitute a genuinely stable extension boundary.
• Prioritize fixing the root cause:Adding a fallback means the root cause has not been fully resolved. When a fallback is genuinely required, its issue ownership, removal criteria, and verified supporting evidence should be documented.
• Match the size of a change to its behavioral impact:When more than 50 lines of code are added, first report the total line count, the number of lines devoted to validation and fallbacks, and the actual cost of not writing that code.
• Answer three questions before writing safety code:Can the problem actually occur? What happens to users if it does? What is the cost of not writing the code? If any question cannot be answered, do not add the code yet.
• Shorten the validation loop:Covers minimal validation approaches for seven build ecosystems: Gradle, Maven, Go, Node and TypeScript, Rust, Python, and .NET.
• Allow a “no change needed” conclusion:The goal is to solve the problem, not to force code output or opportunistically harden areas the user did not ask to change.
• Provide an audit workflow for existing code:First quantify density, then inspect the worst files, decide whether each item should be removed, moved upward, or retained, and present a results table to the user before making changes.

For defensive code, the skill provides counterexamples in four languages—Java, Go, TypeScript, and Python—to help Agents recognize the same underlying problems across different syntaxes.

Installing lean-mode

Method 1: Import from a URL

If the host supports importing skills from a URL, such as through Vantaloom’s skills page, you can paste the repository URL directly. The host will locate the skill file under skills/lean-mode/.

https://github.com/Timefiles404/lean-mode-skill

Method 2: Copy It into the Workspace

First clone the repository, then copy the skill directory to the location expected by the host. When using the Vantaloom workspace convention, run:

git clone https://github.com/Timefiles404/lean-mode-skill.git
cp -r lean-mode-skill/skills/lean-mode <your-workspace>/.vantaloom/skills/

If the host uses a Claude-style skills directory, copy it to .claude/skills/:

cp -r lean-mode-skill/skills/lean-mode <your-workspace>/.claude/skills/

Method 3: Create the Skill Manually

Create a new skill in the host, then paste in the complete contents of skills/lean-mode/SKILL.md from the repository. Do not omit the frontmatter at the top, because the host uses its description to determine when to load the skill.

Basic Usage Workflow

After installation, lean-mode primarily relies on its skill description to enter the context when needed. It should be triggered when an Agent is about to add validation, exception handling, an abstraction layer, a fallback, or an additional safety subsystem, or after it has already run builds and tests multiple times in one iteration.

Scenario 1: Determine Whether New Validation Is Needed

1. First locate the data source and determine whether it comes from external input, an interface boundary, or another untrusted source.
2. Check whether the same constraint has already been validated at the trust boundary.
3. Determine whether the problem can actually occur, how users would be affected, and the cost of omitting the validation.
4. If the data is already trusted after entering the system, do not repeatedly add the same type of runtime validation at every layer.

For example, when an Agent wants to add Objects.requireNonNull repeatedly across several internal methods, it should not do so merely because a parameter “could theoretically be null.” Instead, it should first trace the actual source of the null and determine whether validation has already been performed at the boundary.

Scenario 2: Handle Exceptions

When an Agent is about to catch an exception and return a default value, it should first determine whether this handling would hide the root cause. The following pattern requires particular scrutiny:

catch (...) {
    return false;
}

The point is not to prohibit all exception handling, but to avoid converting a traceable failure into a false, null, empty result, or zero value that lacks context. If the business genuinely requires graceful degradation, it should still be evaluated against the exceptions defined in the skill.

Scenario 3: Evaluate an Abstraction Layer

If an interface currently has only one implementation and the sole reason for creating it is that it “might be replaced in the future,” the Agent should pause and identify the true boundary of change. lean-mode does not reject abstraction; it opposes prematurely creating indirection when there is no current requirement or stable boundary.

Scenario 4: Shorten Builds and Tests

1. Prefer reusing existing build processes to avoid unnecessary repeated cold starts.
2. Preserve incremental artifacts instead of habitually running clean.
3. Start with the smallest command that only compiles, checks the relevant module, or runs a single test.
4. After the minimal validation passes, gradually expand to module-level or complete test suites.
5. Limit repeated invocations and avoid rerunning the same command when the code has not changed.
6. Set reasonable timeouts for commands that might hang, and analyze the first root cause after a failure.

The complete skill text in the README provides “run only this” minimal validation loops for seven build ecosystems. In practice, these examples should be replaced with real commands that can be executed directly in the project.

Auditing Existing Overly Defensive Code

lean-mode includes a “measure first, then remove” audit workflow for projects that have accumulated extensive validation, fallback, or exception-swallowing logic.

1. Search and quantify:Use the language-specific search patterns in the appendix to measure the number and density of relevant patterns.
2. Narrow the review scope:Inspect only the five files with the highest concentration of issues instead of auditing the entire repository from the outset.
3. Classify each item:Mark each piece of logic as “remove,” “move up,” or “keep.” “Move up” usually means consolidating validation at the actual trust boundary.
4. Report before modifying:Present the audit table to the user for a decision before making changes. Do not perform large-scale deletions without confirmation.
5. Validate in batches:After making changes, validate with the smallest build and test scope, then expand the scope based on the results.

This workflow emphasizes observability, user choice, and reversibility rather than turning “reducing defensive code” into another uncontrolled large-scale refactor.

Customizing SKILL.md

SKILL.md is itself Markdown and can be edited directly. The following three types of customization are the most valuable.

Replace Project Validation Commands

Replace the generic commands in Section 7 with actual “compile only” and “run one test only” commands that work in the current project. A command that can be copied and executed directly usually constrains Agent behavior more effectively than an abstract principle.

Adjust Search Patterns

Modify the search rules in the appendix to match the project’s coding style. For example, a Java project may use Guava Preconditions, or it may primarily use Objects.requireNonNull. Search patterns should reflect the actual codebase.

Adjust the Reference Density

The skill uses one validation check every 200 to 500 lines as an empirical reference, but this is not a universal standard. Parsers, protocol boundaries, and business CRUD code have different reasonable validation densities, which should be adjusted according to domain risk and data sources.

Advanced Usage Recommendations

• Keep the exceptions in context too:The criteria in the skill are heuristics, not theorems. Do not reduce them to simplistic slogans such as “do not validate” or “do not catch.”
• Require the Agent to report the composition of changes:When it adds more than 50 lines, have it clearly state the total line count, the number of validation and fallback lines, and the cost of not implementing that logic.
• Expand validation scope gradually:Start with the relevant file, a single test, or a module before moving to a broader test scope, avoiding a full build after every change.
• Justify fallbacks with evidence:When a fallback must remain, document the specific source of the issue, the verified findings, and the conditions for future removal. Do not rely on unverifiable claims such as “some environments might fail.”
• Treat “no modification” as a valid result:If existing logic already solves the problem, or new code offers no clear benefit, allow the Agent to state directly that no changes are necessary.

Capability Boundaries and Optional Companion Tooling

lean-mode changes model tendencies, not model capabilities. It cannot force a model to stop writing a particular type of code; it can only place the criteria into context at the appropriate time. It is therefore useful, but it provides no guarantee.

It is also not a static analyzer and does not automatically read or scan code. For the audits described in the appendix, the Agent must run the relevant search commands and evaluate the results itself.

The optional Vantaloom plugin of the same name continuously places a compressed version of the guidelines into each turn’s dynamic context and provides tool-result footnotes and a lean_review tool. The plugin provides ongoing reminders, while the skill supplies the complete criteria. The skill can still be used independently without installing the plugin.

The project repository is available at lean-mode-skill on GitHub and is licensed under the MIT License.

Conclusion

The value of lean-mode does not lie in mechanically reducing code, but in ensuring that every validation check, exception handler, abstraction, fallback, and validation command has a clear justification. After installation, customizing it with the project’s actual commands, search patterns, and risk-based density can help coding Agents focus more closely on root causes and establish shorter, more reliable engineering feedback loops.