DEV Community: Lars Moelleken

Stop Prompting Like It's 2024

Lars Moelleken — Sat, 08 Aug 2026 23:12:37 +0000

Coding agents got much better.

Our prompts often didn't or we use inefficient chat messages.

In 2026, I don't try to find magical sentences that somehow make the model smarter.

I try to make the task hard to misunderstand, hard to game, and easy to verify.

After years of using LLMs on real codebases, these are the ten prompting patterns I keep coming back to.

1. Call It a "First Draft" and Attack It

Instead of

Is this implementation correct?

Try

This is a first draft implementation.

Review it critically.

Assume there are mistakes.

Find concrete failures and prove them with tests.

How

Change the task from confirmation to falsification.

For important changes, I go one step further and review the implementation in a fresh context:

You are reviewing a first draft.

You get:

- the requirements
- relevant repository context
- the patch
- the tests

Assume the implementation may be wrong.

Find evidence.

Do not give the reviewer the previous agent's 40-message explanation of why every decision was supposedly brilliant.

Why

Framing changes the task.

These are not equivalent:

Is this correct?

Review this.

Assume this is wrong. Prove it.

The first invites confirmation.

The last explicitly asks for adversarial evidence.

If the same agent wrote the code, its context also contains all the reasoning that justified the implementation. A fresh review removes part of that anchoring.

Humans already struggle to review their own decisions objectively.

Giving confirmation bias a GPU didn't magically solve it.

2. Use Sharp Language and Remove Hedge Words

Instead of

Could you maybe improve the tests where appropriate?

Try

The current tests are insufficient.

Add tests until they can expose incorrect behavior.

Or my less diplomatic version:

Add tests until you find at least one real regression.

If your tests cannot distinguish broken behavior
from correct behavior, your tests are shit anyway.

How

Use clear classifications:

INSUFFICIENT
INCORRECT
BROKEN
REJECTED
NOT DONE

And remove unnecessary hedge words:

maybe
perhaps
try
consider
if possible
where appropriate

The profanity is not the important part.

The classification boundary is.

And there is a funny bit of 2026 evidence here.

When Claude Code's source was accidentally exposed through a published source map in March 2026, people inspecting it found explicit frustration detection that classified phrases including profanity.

So wording is not necessarily just some irrelevant wrapper around the "real" request.

Modern agent harnesses can inspect language before we even get to what the model itself does with those tokens.

Why

Compare:

Maybe review this.

with:

This is incorrect.

Discard this approach and find the failure.

They communicate different:

expectations
confidence levels
quality thresholds
acceptable continuations

Human communication contains lots of social cushioning because humans have feelings.

The coding agent doesn't need emotional cushioning.

It needs to know which side of the acceptance boundary its output currently occupies.

Ambiguity is an API bug.

3. Close the Cheap Escape Hatches

This may be the most important pattern.

Instead of

Improve test coverage.

Try

Increase test coverage by at least 10 percentage points.

Do not add tests that merely execute code.

Use mutation testing to verify that the new tests
detect behavioral changes.

Investigate surviving mutants.

How

Combine three things:

measurable floor
+
anti-cheating constraint
+
independent verification

The same pattern works outside testing.

Bad:

Improve performance.

Better:

Reduce median runtime by at least 20%.

Do not increase peak memory usage by more than 5%.

Run the benchmark at least five times.

Report the median before and after.

Or:

Reduce PHPStan errors in this module from 47 to 0.

Do not add ignores.

Do not add baseline entries.

Do not weaken types.

Why

Agents are extremely good at satisfying badly written requirements.

Ask:

Improve coverage.

and technically this qualifies:

81.20% → 81.21%

Mission accomplished.

Human disappointed.

Machine wondering why the human keeps moving the goalposts.

Coverage alone has another cheap escape:

A test can execute a line without meaningfully checking its behavior.

That is why:

coverage

becomes more useful when combined with:

mutation testing

Coverage asks:

Did this code execute?

Mutation testing asks:

Would your test notice if this code were wrong?

Much better.

My general rule:

If there is a stupid but technically valid way to satisfy your prompt, assume an agent will eventually find it.

Close the loophole before execution starts.

4. Make the Agent Prove the Bug Before Fixing It

Instead of

Fix this bug.

Try

Do not change production code yet.

First reproduce the suspected bug with a failing automated test.

Only after the failure is proven:

1. implement the smallest fix
2. rerun the regression test
3. run the complete validation suite

How

Force this sequence:

Hypothesis
    ↓
Reproduction
    ↓
Evidence
    ↓
Implementation
    ↓
Verification

Not this:

Suspicious code
    ↓
Plausible theory
    ↓
Immediate rewrite
    ↓
Tests still green
    ↓
"Fixed!"

Why

Without reproduction, you may never know whether:

the reported bug actually existed
the agent's explanation was correct
the patch fixed that specific bug
the new test protects against regression

Coding agents can produce plausible fixes extremely quickly.

That makes evidence more important, not less.

Implementation is becoming cheap.

Knowing whether you are implementing the right thing isn't.

5. The Model Never Decides When It Is Done

Instead of

Make sure everything works.

Try

DONE WHEN:

- the regression test fails before the fix
- the regression test passes afterward
- the complete test suite passes
- static analysis passes
- mutation score does not decrease
- the public API remains unchanged
- no unrelated files are modified

And require evidence:

Before finishing, report:

- commands executed
- test results
- static-analysis result
- mutation result
- remaining assumptions

How

Move the stopping condition outside the model.

The model saying:

Everything looks correct.

is not verification.

The environment saying:

428 tests passed
PHPStan: 0 errors
Infection MSI: 94%

is considerably more useful.

Why

The model should not simultaneously be:

author
+
reviewer
+
QA department
+
final authority

That is an absurd control system.

For one of my PHP projects, the gates might be:

Codeception
PHPStan
Infection
php-cs-fixer

For another project they may be completely different.

The exact tools do not matter.

The principle does:

The model proposes. Mechanical systems verify.

And BLOCKED must be a valid result.

If a requirement cannot be satisfied under the current constraints:

STOP.

Provide:

- the blocking requirement
- evidence
- affected constraint
- smallest contract change that would unblock the task

Do not silently weaken the requirement.

Sometimes the correct output from an agent is:

I cannot prove this.

That is far better than fabricated success.

6. Define Scope, Non-Goals, and Restart Rules

Coding agents notice neighboring problems.

Lots of them.

That can turn:

Fix validation bug.

into:

I introduced ValidationFrameworkFactoryStrategyManager
and migrated 37 unrelated files.

A timeless software tradition, now automated.

Try

GOAL

Fix the validation regression.

CONSTRAINTS

- keep the public API unchanged
- do not introduce dependencies
- do not modify unrelated modules

NON-GOALS

- no framework migration
- no API redesign
- no general validation cleanup
- no unrelated formatting changes

And if the agent violates the contract, don't politely negotiate with the patch.

This patch is incorrect.

Problems:

1. the public API changed
2. the regression is not reproduced
3. unrelated files were modified

Discard this implementation.

Restart with:

1. failing regression test first
2. minimal production change
3. public API unchanged
4. complete validation
5. report mechanical evidence

How

Define both:

what to solve

and:

what deliberately not to solve

Then make rejection explicit when the result crosses those boundaries.

Why

Scope is part of correctness.

A technically elegant solution that solves three extra architectural problems may be a terrible patch.

Explicit non-goals make YAGNI promptable.

And an explicit restart is much clearer than spending six follow-up prompts trying to repair an approach that violated the basic contract from the beginning.

Treat the output like a failed build:

FAILED
WHY
EXPECTED
RETRY

Not like a colleague whose self-esteem depends on keeping 70% of the previous patch.

7. Give Agents Larger Planning Horizons, but Small Implementation Steps

Instead of

Plan the next step.

Try

Plan the next three months.

Create falsifiable milestones.

For every milestone define:

- objective
- evidence
- dependencies
- risks
- explicit non-goals
- completion criteria

Then:

Implement milestone 1 only.

Keep the diff small.

Do not begin milestone 2.

How

Separate:

planning horizon

from:

implementation size

My preferred model is:

Think in months.

Plan in milestones.

Implement in small diffs.

Verify continuously.

Why

Human project management evolved around human execution speed.

A developer might work two days on "the next step."

An agent may finish it before you've finished your coffee.

If every tiny step requires another human prompt, the human becomes the scheduler.

But giving the agent a large planning horizon does not mean:

Autonomously rewrite this repository for three months.

It means the agent understands where today's small change is supposed to lead.

Macro-plan.

Micro-execute.

8. Treat Context as an Engineering Dependency

A perfect prompt with wrong context produces a beautifully structured mistake.

Instead of only

Refactor the parser.

provide or derive:

PROJECT CONTEXT

- production runs PHP 8.3
- Parser.php contains canonical normalization behavior
- empty string and null have different domain semantics
- public APIs are consumed by external packages
- a previous refactor broke empty-string handling
- static analysis runs at maximum configured level

But don't solve the problem by dumping the entire repository into the context window.

Use:

Identify the files, tests, documentation, decisions,
configuration and historical constraints relevant to this task.

Explain why each selected context source matters.

Ignore unrelated project history.

How

Treat context selection as part of the task.

The useful target is not:

maximum context

but:

maximum relevant context

Why

Real implementation decisions depend on project-specific facts:

supported runtime versions
architecture
deployment constraints
existing tests
backwards-compatibility promises
dependency versions
previous regressions
CI behavior
intentionally duplicated code
failed previous approaches

None of that can reliably be reconstructed from:

You are an expert senior developer.

Context is not decoration around the prompt.

Context is a dependency of the task.

9. Use L2 Meta-Prompts as Prompt Compilers

This is where I think prompting gets much more interesting.

A normal prompt tells the agent what to do.

An L2 meta-prompt creates the correct project-specific prompt first.

L1

Fix the parser bug.

Add tests.

Run static analysis.

Still generic.

L2

You are not implementing the task yet.

Your job is to create the project-specific operational prompt
that another coding agent should execute for this task:

TASK:
Fix the parser bug without changing existing public behavior.

Inspect the repository before creating the prompt.

Resolve project-specific facts from repository evidence.

At minimum determine:

- language and supported runtime versions
- package/dependency manager
- actual test framework(s)
- exact relevant test commands
- static-analysis tools and configured levels
- formatter/linter commands
- mutation-testing tools, if configured
- CI validation relevant to this change
- architecture and repository conventions
- public API / backwards-compatibility constraints
- relevant existing tests
- likely affected components
- AGENTS.md, CONTRIBUTING.md, ADRs or equivalent instructions
- historical regressions relevant to this task

Do not invent tools, commands or constraints.

Derive them from repository evidence such as:

- dependency manifests
- lock files
- CI configuration
- test configuration
- static-analysis configuration
- formatter configuration
- mutation-testing configuration
- existing scripts
- documentation
- existing tests

Then generate ONE ready-to-execute operational prompt.

Do NOT write generic instructions such as:

"run the tests"
"use the project's test framework"
"run static analysis"

when the repository allows the actual command to be resolved.

Write concrete instructions such as:

"Run `vendor/bin/codecept run unit`"

or:

"Run `composer phpstan`"

only when those exact commands are supported by repository evidence.

Structure the generated prompt as:

GOAL
PROJECT CONTEXT
RELEVANT COMPONENTS
CONSTRAINTS
NON-GOALS
IMPLEMENTATION APPROACH
VERIFICATION
DONE WHEN

If a required fact cannot be determined,
mark it UNKNOWN instead of guessing.

Do not implement the task.

Output only the final project-specific operational prompt.

How

The L2 prompt acts like a compiler:

Task
+
Repository
        ↓
Discover project facts
        ↓
PHP version
test framework
exact commands
CI gates
static analysis
architecture
BC constraints
existing tests
        ↓
Compile
        ↓
Project-specific L1 operational prompt

So the final generated prompt might contain:

Tests use Codeception.

Add the regression to:
tests/unit/ParserTest.php

Run:
vendor/bin/codecept run unit

Static analysis:
vendor/bin/phpstan analyse -c phpstan.neon

Mutation testing:
vendor/bin/infection

instead of:

Run the project's tests and static analysis.

Why

The correct operational prompt for:

a small open-source PHP library

is not the same as the correct prompt for:

a twenty-year-old internal IAM system

even when both happen to use PHP.

The human should provide the intent.

The repository already contains much of the operational context.

The L2 prompt combines them.

That scales much better than manually maintaining one universal monster prompt containing every rule accumulated since humans discovered Markdown.

Context is project-specific. Good operational prompts should be project-specific too.

10. Let Successful Sessions Teach Future Sessions

Agent sessions are temporary.

Project knowledge shouldn't be.

After a useful discovery

That worked.

Update AGENTS.md with the reusable constraint
that prevented the original failure.

Do not record task-specific implementation history.

Record only knowledge that should change how future agents
operate in this repository.

Bad memory:

On Tuesday we changed Parser.php because test 17 failed.

Useful memory:

Empty strings and null represent different domain states.

Normalization code must preserve that distinction.

How

Promote only durable findings from temporary working context into persistent project instructions.

The loop becomes:

Prompt
    ↓
Execute
    ↓
Verify
    ↓
Discover
    ↓
Learn
    ↓
Update project context
    ↓
Better next prompt

Why

Without learning, tomorrow's agent can repeat yesterday's mistake.

But storing everything is just as bad.

Eventually AGENTS.md becomes a landfill of obsolete task history that poisons future context.

So memory has to earn its place.

Ask:

Would knowing this change how a competent agent should approach a future task?

If yes, preserve it.

If not, let it disappear.

Forgetting is part of good context management too.

The Pattern Behind All Ten

These techniques look different, but they keep collapsing into the same operational contract:

Operational Prompt
    =
    Goal
    + Context
    + Constraints
    + Verification
    + Done When

Goal

What observable result must exist?

Context

Which project-specific facts affect the solution?

Constraints

Which shortcuts and changes are forbidden?

Verification

Which external tools determine whether the result is correct?

Done When

What exact evidence allows execution to stop?

That is how I increasingly prompt coding agents in 2026.

Not:

You are a world-class software engineer.

Think step by step.

Please provide your best possible solution.

But:

Here is the goal.

Here is the relevant context.

Here are the boundaries.

Here is how reality will be measured.

Here is exactly when you are done.

Then, for important work:

This is a first draft.

Assume it is wrong.

Break it.

Prove the failure.

And as projects get larger, I increasingly don't even want to manually write that operational prompt.

I want an L2 meta-prompt to inspect the project and compile it for me.

Because the future of prompting is not finding increasingly clever magic words.

It is requirements engineering for machines that execute ridiculously fast.

Sharp language matters.

Context matters more.

Evidence beats confidence.

And the machine does not get to decide that the machine is correct.

You Bought the Machine. Now Build the Software Factory.

Lars Moelleken — Sun, 02 Aug 2026 12:03:19 +0000

// follow-up post from ...

Lars Moelleken

Aug 2

AI Makes Bad Developers Faster Too

#ai #programming #productivity #softwaredevelopment

5 min read

A factory owner buys a machine that works 30x faster than his employees.

He drops it into the middle of the workshop and switches it on.

Within an hour, it produces hundreds of parts.

Some are correct.

Some are nearly correct.

Some only look correct until somebody puts weight on them.

Nobody can reliably tell the difference.

The drawings are outdated. The measuring equipment is broken. Important specifications exist only inside the head of one senior employee. Quality control is one exhausted person saying:

Looks fine to me.

Production has increased.

Useful production has not.

That is software development with coding agents.

We bought the machine.

Now we need to build the factory.

The Machine Is Not the Factory

Coding agents can already:

inspect repositories
implement features
write tests
execute commands
analyze failures
refactor code
review diffs
open pull requests

That is real production power.

It is not engineering maturity.

A factory also needs:

specifications
tolerances
controlled environments
measuring equipment
inspections
stop conditions
traceability
accountability

Without those things, an agent is just a very fast developer with incomplete context and no responsibility for the production incident.

We already had developers like that.

Now they scale horizontally.

Stop Writing Wishes. Write Work Orders.

This is not a useful agent task:

Improve customer validation.

Add tests where appropriate.

Do not break anything.

“Do not break anything” is not a requirement.

It is a prayer.

A useful task defines the part:

Reject an empty customer identifier before database access.

Required behavior:
- Reject an empty string.
- Reject whitespace-only input.
- Throw InvalidArgumentException.
- Include "customerId" in the exception message.

Constraints:
- Preserve public interfaces.
- Do not add dependencies.
- Do not modify unrelated files.
- Do not suppress static-analysis errors.

Verification:
- Add a regression test that fails before the fix.
- Run PHPUnit.
- Run PHPStan.
- Run PHP-CS-Fixer in dry-run mode.
- Report commands, exit codes, and results.

No change is a valid result if the defect cannot be reproduced.

That is not clever prompting.

It is a work order.

The agent does not need encouragement.

It needs dimensions.

Get the Blueprints Out of People’s Heads

Critical software knowledge still lives in:

old tickets
Slack messages
abandoned wiki pages
pull-request comments
production incidents nobody documented
comments saying DO NOT TOUCH
“ask Thomas”

A senior developer may understand the invisible rules around a codebase.

The agent sees files.

It does not see tribal knowledge.

Store durable knowledge (ADRs, Skills, Docs, ...) in predictable places:

AGENTS.md
README.md
docs/architecture.md
docs/domain-rules.md
docs/decisions/
docs/runbooks/

But documentation is not enough.

Make important rules executable.

Do not merely write:

Controllers must not execute SQL.

Add an architecture test.

Do not merely write:

Money uses integer cents.

Encode it:

<?php

declare(strict_types=1);

final readonly class Money
{
    /**
     * @param int<0, max> $cents
     */
    public function __construct(
        public int $cents,
    ) {
        if ($cents < 0) {
            throw new InvalidArgumentException(
                'Money cannot contain negative cents.',
            );
        }
    }
}

The best documentation is a system that rejects invalid construction.

Define Tolerances

Factories do not ask machines to produce “high-quality parts.”

They define tolerances.

Software needs the same thing:

Public APIs must not change.

Domain code must not depend on HTTP infrastructure.

Only repository classes may execute SQL.

No new production dependencies.

PHPStan errors must not be suppressed.

Every skipped verification command must be reported.

A vague instruction forces the model to invent its own definition of quality.

Then everybody acts surprised when it chooses convenience.

Do not ask whether the model was smart.

Ask whether the result stayed inside the tolerances.

Do Not Let the Machine Inspect Itself

An agent saying:

All tests pass.

is not evidence.

It is text generated by the same system that generated the code.

Require:

exact command
exact exit code
relevant output
tested scope
skipped checks
reason for every skipped check

For a PHP project:

composer test
vendor/bin/phpstan analyse --no-progress
vendor/bin/php-cs-fixer fix --dry-run --diff

Where configured:

vendor/bin/infection --min-msi=80

The result must be explicit:

PASSED
FAILED
SKIPPED
NOT AVAILABLE

Not:

Looks good.

Not:

Should work.

Not:

I could not run the tests, but the change is straightforward.

A factory with broken gauges can produce consistently broken products.

Consistency is not correctness.

Add a Stop Button

Agents assume that every task must produce a patch.

That creates ceremonial changes:

pointless refactors
speculative abstractions
unnecessary validation
comments explaining syntax
tests that simply repeat the implementation
unrelated cleanup nobody requested

Sometimes the correct result is:

No change required.

The bug may already be fixed.

The report may be wrong.

Another service may own the failure.

The required external system may be unavailable.

The requested change may make the architecture worse.

Require reproduction first:

Reproduce the reported behavior before modifying production code.

If it cannot be reproduced:
1. Report the scenarios tested.
2. Report the commands executed.
3. Report the observed behavior.
4. Identify unavailable dependencies.
5. Do not create a diff merely to appear productive.

Evidence is progress.

A diff is not.

Review Risk, Not Every Screw

Reading every generated line with equal intensity is not a quality strategy.

It is an attention-distribution bug.

Spend human attention on:

authentication
authorization
money
migrations
transactions
concurrency
input boundaries
external integrations
deleted tests
weakened assertions
dependency changes
rollback behavior

Spend less attention on deterministic work protected by automation:

formatting
generated DTOs
repetitive mappings
mechanical renames
schema-generated clients

A decorative screw and a structural bolt do not deserve the same inspection.

That is not laziness.

That is engineering.

But there is no free shortcut:

Reading less code requires testing more behavior.

Reading less and testing less is not industrialization.

It is negligence with better branding.

Stop Measuring Tokens

Lines generated do not matter.

Tokens consumed do not matter.

The percentage of AI-written code does not matter.

Measure:

successful repository tasks
human corrections
reverted changes
ignored constraints
regression rate
review time
verification cost
production incidents
reproducibility
recovery time

One thousand generated lines may be useful.

They may also be industrially produced waste.

Your repository is the benchmark that matters.

Not the vendor’s multiplier.

Someone Still Owns the Result

When generated code breaks production, responsibility cannot be assigned to the model.

The model does not:

own the repository
answer customers
restore corrupted data
carry legal liability
receive the incident call at three in the morning

A real workflow defines:

who approved the task
who defined acceptance criteria
which checks were mandatory
which checks ran
who accepted skipped verification
who reviewed high-risk changes
who approved deployment
how rollback works

This is not new AI bureaucracy.

This is engineering accountability that should already have existed.

The machine simply exposes its absence.

Start With One Production Line

Do not build a giant internal AI platform first.

That is how companies spend a year automating work they never understood.

Choose one repeatable task:

dependency updates
regression tests
DTO generation
static-analysis fixes
mechanical migrations
deterministic renames

Then define:

the input
the required change
the constraints
the environment
the verification
the risk level
the evidence
the stop conditions
the approval
the learning after failure

That is already a software factory.

Small, but real.

The Developer Becomes the Factory Builder

The developer is not disappearing.

The work is moving.

Less value comes from manually typing predictable code.

More value comes from:

defining correctness
encoding constraints
designing architecture
building verification
identifying risk
measuring outcomes
investigating failures
deciding when the machine is wrong

A master carpenter should not spend every day producing identical shelf pins.

But somebody still needs to understand material, structure, load, and failure.

Otherwise the factory produces furniture efficiently until somebody sits on it.

The same applies to software.

The agent is not the factory.

The model is not the production system.

Generated code is not automatically the product.

The factory is the system of constraints, evidence, inspection, and responsibility around the machine.

You bought the machine.

Stop admiring how fast it moves.

Build something that can reject its garbage.

AI Makes Bad Developers Faster Too

Lars Moelleken — Sun, 02 Aug 2026 11:27:04 +0000

The Circular Saw, the Apprentice, and the Software Factory

A circular saw does not turn a bad carpenter into a good one. It merely allows him to destroy wood faster.

A skilled carpenter still uses the circular saw. Refusing modern tools would not make him more professional, only slower. The difference is that he understands the material. He knows how wood behaves, where tension builds, how grain direction affects a cut, and when a clean-looking result is structurally wrong.

The machine provides speed and force. The carpenter provides judgment.

The same is true for LLMs in software development.

An experienced developer can use an LLM to explore a codebase, generate implementations, write tests, investigate failures, and compare possible designs much faster than before. But the tool does not provide the developer’s understanding of the system. It does not automatically know which assumptions are valid, which abstractions belong together, or which apparently elegant solution will create maintenance problems six months later.

An LLM amplifies the process around it.

In a disciplined engineering process, it accelerates useful work. In a weak process, it accelerates confusion, duplication, security problems, and confidently formatted nonsense.

Why the Apprentice Still Needs the Hand Saw

This does not mean beginners should avoid LLMs completely. It means they must not outsource the part of learning that creates judgment.

A carpenter’s apprentice may work with a hand saw, a plane, and a chisel before relying entirely on powered machinery. Not because manual tools are morally superior or because suffering builds character, although humanity remains strangely attached to that idea. The apprentice uses them because direct contact with the material teaches lessons that the machine can hide.

The same principle applies to programming.

A developer must learn to follow control flow, model data, understand HTTP, inspect SQL, debug failures, reason about state, and recognize the consequences of architectural decisions. Those skills create the mental models required to evaluate generated code.

Without them, the developer may be able to produce software but cannot reliably judge it.

The output may compile. The tests may pass. The code may even look clean. Yet the developer does not know whether the implementation fits the surrounding system, whether important cases are missing, or whether the design is carrying assumptions that were never verified.

The problem is therefore not that the apprentice used a machine. The problem is that the machine allowed the apprentice to skip learning what a correct cut actually is.

From Better Tools to Better Production

Once the craft is understood, the next question is larger than individual skill.

A good carpenter with a circular saw can build faster, but industrial production does not emerge merely because every carpenter receives a more powerful tool.

Industrial production requires standards, repeatable processes, defined components, quality controls, inspections, and clear responsibility for the final product.

This is where the IKEA analogy becomes useful.

IKEA does not scale because every employee is the world’s greatest cabinetmaker. It scales because products are designed around standardized materials, documented parts, repeatable manufacturing, controlled tolerances, predictable logistics, and assembly processes that work across millions of units.

The quality does not depend solely on one person’s memory or intuition. Knowledge has been moved into the production system.

Software development has not fully reached that point.

We have reusable packages, automated tests, static analysis, CI pipelines, containers, coding standards, observability, and increasingly capable coding agents. But many software systems still depend on undocumented assumptions, local knowledge, inconsistent architecture, incomplete tests, and developers who happen to remember why something was built ten years ago.

That is not industrial production. It is craft production with increasingly powerful machinery.

The Steam Engine Arrived Before the Factory

This is why calling LLMs the industrial revolution of software is premature.

They are closer to the steam engine arriving before we have finished building the factory.

The machine is powerful. It can multiply output dramatically. But the surrounding structures are immature. We do not yet have universally reliable standards for generated code, consistent inspection methods, stable responsibility models, or production systems designed around autonomous implementation.

So we place the steam engine inside the existing wooden workshop.

Sometimes it powers a productive operation. Sometimes it shakes the building apart.

The limiting factor is no longer only how quickly code can be written. The limiting factor becomes whether requirements are clear, context is available, assumptions are verified, results are tested, and decisions remain understandable after the agent has finished.

LLMs expose this distinction brutally.

When implementation becomes cheaper, every weakness around implementation becomes more visible. Poor specifications produce more incorrect code. Weak architecture produces more inconsistent code. Missing tests allow more regressions. Undocumented decisions become harder to reconstruct because the volume of change increases.

The faster the machine, the more important the production system becomes.

Generated Code Is Not Yet IKEA

There is another side to the IKEA analogy.

An IKEA cabinet can be perfectly adequate. It may be inexpensive, consistent, easy to replace, and durable enough for its purpose. It does not become inferior merely because it was not handcrafted.

Generated code should be judged the same way.

Code does not gain value because a human typed every character. Nor does it lose value because an LLM produced most of it. What matters is whether it solves the right problem, fits the system, remains maintainable, handles failure safely, and can be verified.

But IKEA furniture arrives with defined parts, known materials, tested connectors, numbered steps, and a repeatable assembly process.

Generated software usually does not.

The output may look standardized, but the assumptions behind it are often specific to the current prompt, context window, repository state, and model behavior. Two apparently similar generations may differ in subtle but important ways. The developer cannot simply assume that generated code is an interchangeable industrial component.

We have the appearance of mass production without all the guarantees of mass production.

That is why the human role shifts rather than disappears.

The Developer Becomes Responsible for the System

When code generation becomes cheap, manually producing every line becomes less important. Understanding the system becomes more important.

The developer’s responsibility moves toward:

defining the actual problem,
providing relevant context,
choosing architectural boundaries,
identifying dangerous assumptions,
verifying behavior,
evaluating trade-offs,
and preserving the reasoning behind decisions.

This is not a retreat from engineering. It is engineering at a higher level.

The carpenter using a circular saw is not less skilled because the blade moves automatically. Skill appears in how the cut is planned, how the material is secured, how errors are prevented, and how the result is inspected.

Likewise, a developer does not prove competence by typing code slowly without assistance. Competence appears in the ability to direct the tool, detect when it is wrong, and integrate its output into a reliable system.

The goal is not to protect manual coding as a ritual.

The goal is to ensure that increased production does not outrun understanding.

The Actual Path Toward the Software Factory

The future of software development is therefore not simply more code generated by larger models.

It is the gradual construction of a production system around those models.

That system needs explicit requirements, constrained context, architecture rules, static analysis, automated tests, security checks, traceable decisions, reproducible agent workflows, and clear human approval points.

Only then does the analogy begin to move from circular saw to IKEA.

The individual developer still needs craftsmanship, because someone must understand the material and recognize failure. The apprentice still needs fundamentals, because judgment cannot be delegated before it exists. The organization needs production standards, because faster tools alone do not create reliable outcomes.

LLMs are neither magical replacements for developers nor merely fancy autocomplete.

They are powerful machinery.

A skilled craftsperson can use that machinery to produce better work faster. A weak process can use it to manufacture defects at scale. And an immature industry can mistake increased output for industrialization.

We have the circular saw.

We may even have the steam engine.

But we are still building the factory.

Distill Coding Agent Learnings

Lars Moelleken — Thu, 16 Jul 2026 09:32:14 +0000

Repo: https://github.com/voku/agent-loop

Website: https://voku.github.io/agent_loop_demo/

Your Coding Agent Can Write Code. Keep the Work Reliable.

Coding agents are already surprisingly good at changing code.

The harder problem is everything around the change.

What exactly was requested?

What is the agent allowed to touch?

Which repository facts matter?

Which validation actually ran?

Does that validation still belong to the current implementation?

What should happen next?

And when something useful was learned, should it influence the next task, become durable guidance, or eventually disappear into a test, static-analysis rule, or CI check?

The obvious response has often been:

Give the agent more memory.

So repositories slowly acquire things like:

MEMORY.md
project-rules.md
agent-notes.md
lessons-learned.md
MEMORY_FINAL.md
actually-final-memory.md

Soon the coding agent receives old decisions, temporary workarounds, copied transcripts, stale debugging notes, abandoned architecture ideas, and rules nobody remembers approving.

It has more context.

It does not necessarily have better context.

At some point, memory becomes landfill.

That was the problem I wanted to solve with voku/agent-loop.

Not by building another coding agent.

By building a governed workflow around the coding agent you already use.

The everyday loop should stay small

The internals of Agent Loop are deliberately more sophisticated than its ordinary host contract.

For normal governed work, the coding agent starts here:

vendor/bin/agent-loop enter PROJECT-123 --format=json

The result exposes the important state:

mutation_ready
next_action_kind
next_action

The host follows that result.

It performs the current work.

Then:

vendor/bin/agent-loop finish PROJECT-123 --format=json

And again follows the returned next action until the workflow converges.

Conceptually:

developer intent
      ↓
agent-loop enter <task>
      ↓
canonical next_action
      ↓
coding agent works
      ↓
agent-loop finish <task>
      ↓
validation · review · learning
      ↓
repeat or complete

That is the important part.

The coding agent does not need to carry a giant workflow phase machine in its prompt.

It should not have to memorize:

PLAN
MAP
SESSION
RECALL
IMPLEMENT
VALIDATE
REVIEW
LEARN
VERIFY
CLOSE

Those capabilities exist.

But they are implementation details behind the lifecycle.

agent-loop owns the current workflow state and tells the host what happens next.

Why this matters

Without a governed workflow, coding-agent sessions tend to fail in remarkably repeatable ways.

A new chat means reconstructing the task.

The agent guesses whether it should investigate, implement, ask for approval, validate, or review.

Large repositories become giant prompts.

A passing test quietly becomes “done”.

Useful experience disappears after the task.

And project instructions keep growing because deleting prompt text feels more dangerous than adding one more paragraph.

Agent Loop tries to invert those defaults.

The task survives the chat.

Context is selected instead of dumped.

Evidence is tied to the state it actually verified.

The next action is explicit.

And useful learning has somewhere to go other than another permanent Markdown file.

Humans approve intent, not shell commands

A governed workflow should not turn developers into operators of an orchestration CLI.

The developer should still be able to talk naturally to the coding agent.

For example:

Fix PROJECT-123.

Invalid order state transitions must be rejected.
Keep the public API unchanged.
Stay inside the order-state validation and its focused tests.
Run PHPStan and the focused test suite.

The coding agent investigates the repository and prepares a candidate Contract:

Goal:
Reject invalid order state transitions.

Scope:
Order-state validation and focused tests.

Non-goals:
Do not redesign the order aggregate.
Do not change the public API.

Validation:
composer phpstan
composer test

When the lifecycle reaches a real human-authority boundary, the agent presents that exact decision.

The developer can answer:

Approved.

Or:

No. Keep the repository layer untouched.

Or:

Approved, but do not change the public API.

The coding host records that explicit decision through Agent Loop.

Approval belongs to one concrete Contract revision.

It is not permanent permission attached to a task ID whose meaning can silently change later.

If product intent or approved scope materially changes, the Contract changes too.

That is where human authority is required again.

But ordinary implementation, deterministic validation, review acknowledgement, Learning disposition, Recall outcome logging, local commits, and close-out inside the approved Contract do not need ceremonial confirmation every thirty seconds.

Human authority should stay explicit without becoming human babysitting.

The workflow tells the agent what kind of action comes next

A returned next action is not just a line of text.

It has a kind.

For example:

command
command_template
decision_required
host_work
none

command

means the workflow already knows the exact deterministic operation.

command_template

means the coding agent must fill task-specific values from the request and current repository evidence.

host_work

means actual engineering work is required.

decision_required

means a real human-authority boundary has been reached.

none

means there is no further lifecycle action.

This removes a surprising amount of prompt choreography.

The host does not need to guess:

Is this something I can do myself?

or:

Should I ask the developer now?

or:

Which internal phase comes next?

The lifecycle result already answers that.

Internally, Agent Loop projects the current owner-backed facts and evaluates them through executable policy.

That produces the current:

state
mutation_ready
next_action_kind
next_action

The coding agent follows that result instead of maintaining another slightly different copy of the workflow in prose.

The CLI is the executable contract, not the user experience

Agent Loop exposes a substantial CLI.

You can discover it directly:

vendor/bin/agent-loop help
vendor/bin/agent-loop commands
vendor/bin/agent-loop commands --format=json
vendor/bin/agent-loop commands --format=toon

The top-level command catalog is typed and also drives human-readable help.

That is intentional.

Humans and coding agents should discover the same installed capabilities from the same owner instead of maintaining separate README tables, UI registries, and prompt copies that inevitably drift apart.

But despite the larger command surface, the normal host contract stays small:

enter
  ↓
follow next_action
  ↓
work
  ↓
finish

Specialist commands exist when the current task needs them.

They are capabilities.

They are not mandatory phases.

Skills help perform work. They do not invent workflow state.

Earlier versions of this project leaned more heavily on phase-specific workflow instructions.

That architecture made duplication too easy.

A task-start skill knew one sequence.

A review skill knew another.

A README explained it again.

Eventually there are three correct descriptions of the same workflow, which is software engineering’s traditional method for preparing three future bugs.

The current boundary is stricter.

The lifecycle result remains authoritative.

Skills help the agent perform the current kind of engineering work.

Agent Loop can project focused assets for activities such as:

agent-loop-discipline
agent-loop-workflow
agent-loop-investigate
agent-loop-surgical-edit
agent-loop-code-review
agent-loop-simplify-review

An investigation role is read-only.

A surgical-edit role is for an already-understood bounded change and must escalate instead of quietly widening scope.

A review role inspects the real diff rather than trusting a generated summary.

Broader engineering guidance lives separately in voku/agent-skills, with reusable skills for areas such as:

engineering-codelight
coding-simplicity
php-best-practices
code-review-*

The ownership boundary is intentional:

agent-loop
    workflow authority

agent-skills
    reusable engineering judgment

The agent-skills catalog is optional and separately installed.

Agent Loop does not silently download another engineering rulebook merely because somebody thought seventeen more prompt files looked comforting.

Give the agent less context, but better context

A coding agent does not need the whole repository in its prompt.

It needs enough evidence to make the next engineering decision correctly.

Agent Loop separates repository structure from project guidance because they answer different questions.

Repository structure with agent-map

agent-map provides deterministic PHP repository intelligence.

It can answer questions such as:

Where is this method defined?
Who calls it?
What does it call?
Which symbols are related?
What is the bounded edit context?
What may be affected by changing it?

It can operate structurally and optionally enrich the map through PHPStan when semantic evidence is available.

The important output is not a gigantic graph to admire during architecture meetings.

It is a bounded, source-backed edit context.

And Map output remains derived navigation evidence.

It does not replace the source code.

If the Map says a method has no callers but the current capability cannot observe call edges, that is a capability limit.

It is not proof that the method has no callers.

That difference matters.

Task-specific context with agent-recall-compiler

agent-recall-compiler answers a different question:

Which bounded project knowledge is relevant to this task?

Inputs can include:

approved task intent
repository facts
project guidance
constraints
previous outcomes
LearningNote precedent

The result is replayable task context plus, when applicable, L2 construction material for a concrete project-specific L1 contract.

That L1 typically needs to answer:

Goal
Context
Constraints
Verification
Done When

The point is selection.

Not permanent context inflation.

The goal is not:

Compress the whole repository and six months of transcripts into the model.

The goal is:

Give the agent enough current, verified information to make the next decision correctly.

Deterministic preparation should be automatic

Once a Contract has been approved, enter can prepare the governed execution state.

Conceptually:

approved Contract
      ↓
reconcile required Map state
      ↓
prepare or resume Session
      ↓
prepare governed Run
      ↓
replace stale Recall output
      ↓
compile current Recall
      ↓
return bounded context
      ↓
authorize implementation when ready

The host should not have to memorize that ordering.

If repository discovery can be repaired deterministically, the workflow can repair it.

If an optional capability is unavailable, that does not automatically become a human decision.

This distinction is useful:

Deterministic preparation is choreography, not governance.

If software can safely do it itself, forcing the developer or coding agent to remember another ritual adds ceremony without adding authority.

Working memory should stay temporary

During a task, the coding agent may need mutable state:

assumptions
decisions
checkpoints
validation observations
open questions
resume state

That belongs in agent-session.

A Session is working memory.

It is not permanent project knowledge.

This sounds obvious, but memory systems tend to blur this distinction surprisingly quickly.

A debugging observation may be useful for twenty minutes and misleading two commits later.

Temporary state should remain closable and pruneable.

The durable workflow should preserve only the state and evidence that actually need to survive.

Validation belongs to an exact implementation

An agent saying:

Tests passed.

is useful.

But only if we know which implementation those tests validated.

Validation evidence is bound to the task and exact workflow state, including:

Contract revision
command
exit code
implementation snapshot

Suppose this passed:

composer test

Then the agent changes three files.

The old result is history.

It is not evidence that the new implementation still passes.

The same applies when the approved Contract revision changes.

The system can therefore distinguish:

current validation
superseded by implementation
superseded by Contract revision
missing validation
failed validation

instead of carrying one immortal green checkmark around the repository.

`finish` does not mean “please declare victory”

After implementation, the coding agent calls:

vendor/bin/agent-loop finish PROJECT-123 --format=json

finish does not simply flip a task to done.

It reconciles the current implementation with the current obligations.

Depending on state, it may:

run validation
prepare review evidence
request more host work
surface a human decision
record Learning disposition
log Recall outcomes
close the Session
complete the Run
surface remaining owner work such as Kanban reconciliation

That last distinction is important.

If the governed Run is complete but the linked Kanban card is still active, Agent Loop does not quietly claim everything is finished.

It surfaces the remaining Kanban-owned work.

Evidence stays evidence.

Owner state stays owner state.

The gate ordering itself lives in executable policy rather than another copied checklist.

If validation fails, the canonical next action may be:

next_action_kind = host_work

change the implementation so the declared validation passes

Running the same failed validation forever would not make progress.

Which gives us another useful invariant:

A canonical next action should converge.

If executing the recommended deterministic action always returns the exact same blocker and exact same recommendation, that is a workflow defect.

The coding agent should not invent a private workaround.

Evidence is not authority

This principle appears repeatedly because violating it is an excellent way to build an impressive automation system that is subtly wrong.

A test result is evidence.

It does not approve a scope change.

A review report is evidence.

Its existence does not automatically acknowledge the review.

A generated prompt proves something was rendered.

It does not prove the receiving model used it.

A Map is derived repository structure.

It is not source truth.

A LearningNote is evidence-backed precedent.

It is not active project policy.

And a model sounding extremely confident is mostly evidence that models have become very good at adjectives.

Authority and evidence answer different questions.

The workflow keeps them separate.

Selected guidance is not necessarily useful guidance

Suppose Recall selects a piece of guidance.

That proves:

the system selected it

It does not prove:

the agent consulted it
the agent needed it
the agent applied it
the result improved because of it

Outcome tracking therefore keeps selection and usefulness separate.

A selected item may eventually be judged:

helpful
irrelevant
harmful
not used
unknown

This becomes essential once you start asking whether all that carefully curated prompt material is actually worth its token cost.

Otherwise, you are mostly measuring how often your software successfully copied text into another file.

Computers were already very good at that before LLMs arrived.

Learning should begin with evidence, not policy

This is the part of Agent Loop I find most interesting.

The naive model is:

The agent learned something useful. Save it as a rule.

That promotes evidence far too aggressively.

The current architecture is closer to:

real task
   ↓
Finding
   ↓
LearningNote
   ↓
future Recall
   ↓
later real task
   ↓
observable result
   ↓
new Finding
   ↓
recurrence
   ↓
Dream
   ↓
Proposal
   ↓
human review
   ↓
Memory / Skill / Constraint
   ↓
deterministic enforcement

There are really two loops here.

A fast precedent loop.

And a slower promotion loop.

The fast loop: Finding → LearningNote → future task

A Finding records evidence from real work.

It can preserve things such as:

task identity
observation
validated conclusion
scope
evidence
pattern_key
validation case

A useful solved case may be classified:

ADD_LEARNING_NOTE

That can become a LearningNote.

The important boundary is:

A LearningNote is durable precedent, not active guidance.

It can preserve:

what happened
what failed
why the resolution worked
when to apply it
when not to apply it
how to verify it

A later task may receive that precedent through Recall.

But the note does not:

approve mutation
widen task scope
satisfy validation
create a Skill
create a Constraint
become project policy

It says:

We have seen something like this before. Here is the evidence-backed solved case.

That is much safer than promoting every successful patch into permanent instruction text.

The slow loop: recurrence earns promotion

One solved case rarely deserves policy.

Before promoting a lesson, we want stronger evidence.

Did the pattern recur?

Did it recur across independent tasks?

Was the precedent actually useful?

Was it irrelevant?

Was it harmful?

Is there already an owner for this behavior?

Has later evidence contradicted it?

Could software enforce the invariant instead?

agent-learning provides a deterministic maintenance pass called dream.

When using it through Agent Loop, the workflow owner resolves the configured Learning root for you:

vendor/bin/agent-loop learn dream \
  --report=.agent-loop/dream/latest.json \
  --dry-run

Dream can evaluate accumulated evidence for things such as:

promotion
staleness
replacement
conflicts
outcome coverage
duplicate candidate decisions

It can prepare reviewable candidates.

It does not approve them.

It does not silently rewrite project guidance while everybody sleeps.

A scheduler, if you use one, may decide when to wake this maintenance cycle.

Learning decides whether the evidence warrants a candidate.

A human remains the authority for durable promotion.

Wake frequently.

Promote rarely.

Most tasks should probably learn nothing permanent

This is a feature.

A perfectly good task-level outcome is:

NO_DURABLE_LEARNING

Sometimes the correct conclusion after fixing a bug is:

The bug is fixed.

No new Memory entry.

No new Skill.

No small constitution drafted because one null check was missing on a Wednesday.

Durable Learning should have a higher bar than task completion.

The best memory is sometimes a PHPStan rule

Suppose repeated evidence eventually establishes a stable invariant:

Every X must satisfy Y.

If that property can be detected mechanically, the ideal destination may not be another prompt instruction.

It may be:

PHPStan rule
PHP-CS-Fixer rule
PHPCS sniff
architecture test
unit test
integration test
CI check
typed API
runtime invariant

Then:

repeated evidence
      ↓
reviewed Constraint
      ↓
deterministic enforcement
      ↓
obsolete prompt guidance can disappear

This is where “memory” becomes much more interesting.

The system can distill experience into structure.

Once CI proves the invariant automatically, spending prompt tokens reminding the agent about it on every task is waste.

The lesson has become infrastructure.

The agent can forget it.

One semantic owner per kind of truth

The project is split across focused packages because different kinds of state should have clear owners.

Concern	Owner
Contract / Run authority and lifecycle	`agent-loop`
Git-native work items	`agent-kanban`
Temporary working memory and validation evidence	`agent-session`
Repository structure and code navigation	`agent-map`
Bounded task context and prompt construction	`agent-recall-compiler`
Findings, precedent and durable Learning	`agent-learning`
Portable engineering and review guidance	`agent-skills`

There are optional surfaces too.

agent-ui provides a local human control plane.

agent-loop-runner provides an optional execution plane for isolated coding-host runs.

Internally, agent-graph provides shared deterministic SQLite graph mechanics for Map and Learning.

It deliberately owns none of their domain semantics.

That distinction matters.

The UI should not independently decide what action is legal.

The Runner should not decide that process exit 0 means the governed Run is valid.

A graph database should not become the semantic owner because it contains derived relations.

The boring rule is:

One semantic owner per decision.

It becomes increasingly useful once multiple autonomous tools start touching the same repository.

This is still pre-1.0

One claim deserves particular honesty.

The individual mechanics of the Learning loop exist today:

Finding capture
LearningNotes
bounded Recall selection
L2 / L1 construction
outcome tracking
Dream
reviewed Proposals
Constraints
deterministic enforcement

But I am still dogfooding the harder end-to-end claim:

Does precedent from one real task measurably improve a later independent task, and can repeated evidence eventually become a hard rule that catches a different manifestation of the same mistake?

The project has already proven substantial parts of that path.

What I do not want to do is declare success merely because a LearningNote appeared inside generated context.

Prompt inclusion is not behavioral evidence.

If the same engineering decision would have happened without the precedent, the honest result is:

NO_DEMONSTRATED_VALUE

or:

WITHHELD

That experiment is still active.

I would rather leave the claim open than build a learning system whose main learned behavior is how to congratulate itself.

Try it on one real task

Agent Loop is open source, MIT licensed, local-first, and requires PHP 8.3+.

Install it in an existing Composer repository:

composer require --dev voku/agent-loop

Create the repository-local workflow scaffold:

vendor/bin/agent-loop init scaffold --demo

Install the local coding-agent assets.

For Codex:

vendor/bin/agent-loop init install-assets --agent=codex
vendor/bin/agent-loop init doctor

Then start a fresh Codex session or restart Codex before using the newly installed skills.

That boundary is worth stating explicitly.

install-assets proves that the repository-side files were projected correctly.

It does not prove that an already-running coding host retroactively loaded them.

You can inspect the host-side repository integration with:

vendor/bin/agent-loop init host-status --format=json

Other supported hosts can be selected instead of codex.

Start the governed task

For the demo:

vendor/bin/agent-loop enter DEMO-1 --format=json

Read:

mutation_ready
next_action_kind
next_action

Then do what the current lifecycle asks.

For an unplanned task, that may first be a model-owned Contract template.

The coding agent fills it using:

the developer's request
current repository evidence
the smallest honest scope
repository-supported validation commands

When the result reaches:

decision_required

the host presents the exact human decision.

After approval, call enter again.

Once mutation is authorized, the coding agent implements normally.

Then:

vendor/bin/agent-loop finish DEMO-1 --format=json

Follow the result.

Repeat until complete.

That is the ordinary workflow.

Everything else exists to make those decisions reliable.

The actual interface is still conversation

In day-to-day use, I do not want to manually translate every lifecycle transition into CLI syntax.

I want to tell the coding agent:

Take PROJECT-123.

Reject invalid order state transitions.
Do not change the public API.
Run PHPStan and the focused tests.

The coding agent should inspect the repository, operate the workflow, show me the exact Contract when my authority is required, implement within that boundary, collect evidence, and report the result.

If scope must change, I want that surfaced.

If validation fails, I want the actual failure.

If a Finding is reusable, I want it recorded.

If the task teaches nothing durable, I want the system to say so.

And if repeated evidence eventually produces a rule that PHPStan can enforce, I would rather delete the prompt instruction than celebrate that MEMORY.md grew again.

What changed in my mental model

When I started working on this problem, I thought mostly in terms of memory:

How can the coding agent remember useful things?

That question is too broad.

A better sequence is:

What happened?
    ↓
Is there evidence?
    ↓
Is it useful precedent?
    ↓
Does it recur?
    ↓
Should a human approve it as guidance?
    ↓
Can software enforce it instead?
    ↓
Can we delete the prose again?

That produces a very different system.

Temporary state stays temporary.

Historical precedent stays weaker than current authority.

Validation remains bound to the implementation it actually tested.

Workflow policy lives in executable owners instead of duplicated prompts.

Human decisions stay explicit.

And durable learning has somewhere to go other than an ever-growing pile of Markdown.

The actual lesson

Coding agents do not need to remember everything.

They need:

durable task intent;
explicit authority boundaries;
bounded repository context;
temporary working memory;
validation tied to the current implementation;
one canonical next action;
evidence-backed precedent;
recurrence before promotion;
human-reviewed durable guidance;
deterministic enforcement when possible;
intentional forgetting.

More memory can hide bad context management.

A governed loop exposes it.

The purpose of Agent Loop is not to make developers manually operate a more elaborate state machine.

It is to give coding agents a reliable process they can operate themselves while humans retain authority over the decisions that matter.

The agent can still investigate, edit, test, review, and learn.

But:

I remember
I think
looks good

stop being workflow states.

And once a lesson becomes stable enough that PHPStan, a test, a typed API, or CI can enforce it, the ideal outcome is not that the coding agent remembers it forever.

The ideal outcome is that it no longer has to.

Repo: https://github.com/voku/agent-loop

Demo: https://voku.github.io/agent_loop_demo/

Multi-Line Formatting by Default

Lars Moelleken — Wed, 27 May 2026 01:04:14 +0000

I have reviewed so much code that I usually prefer multi-line formatting by default.

Not because it looks prettier.

Because code review happens line by line. And also tools like static analysis or SQL errors are reported line by line.

PS: in most IDEs you can directly jump into the code by typing or clicking FILE:LINE e.g. in the quick-seach (typing) or in the command line (clicking)

A one-line change should ideally mean:

one thing changed

That sounds obvious, which means we apparently need examples.

The problem with compact code

Compact code often hides the actual change.

A reviewer does not review “the code” in some magical abstract universe.

A reviewer reviews a diff.

And diffs are line-based.

So when multiple independent decisions live on the same line, every change becomes harder to verify.

That is how small changes sneak through review.

Not because reviewers are lazy.

Well, sometimes because reviewers are lazy.

But often because the formatting makes the review harder than necessary.

JavaScript

Bad:

const user = users.find(user => user.id === selectedUserId && user.active && !user.deleted);

Better:

const user = users.find(
  user =>
    user.id === selectedUserId
    && user.active
    && !user.deleted
);

Now a reviewer can see whether someone changed:

user.id === selectedUserId

or:

user.active

or:

!user.deleted

One logical condition per line.

Primitive stuff. Somehow still rare.

SQL

Bad:

SELECT id, name, email, created_at FROM users WHERE active = 1 AND deleted_at IS NULL ORDER BY created_at DESC;

Better:

SELECT
    id,
    name,
    email,
    created_at
FROM users
WHERE active = 1
AND deleted_at IS NULL
ORDER BY created_at DESC;

Now changing:

email

to:

private_email

is one line.

Adding a filter is one line.

Removing a selected column is one line.

The diff no longer looks like someone threw SQL into a blender and called it “compact”.

Conditions

Bad:

if ($user !== null && $user->isActive() && !$user->isDeleted() && $user->hasPermission('admin')) {
    // ...
}

Better:

if (
    $user !== null
    && $user->isActive()
    && !$user->isDeleted()
    && $user->hasPermission('admin')
) {
    // ...
}

Now each condition can be reviewed independently.

This matters when someone changes this:

&& $user->hasPermission('admin')

to this:

&& $user->hasPermission('user')

That is not a formatting change.

That is the kind of thing that becomes a production incident wearing a fake mustache.

HTML

Bad:

<input type="text" name="email" id="email" class="form-control is-invalid" value="{{ email }}" required autocomplete="email">

Better:

<input
    type="text"
    name="email"
    id="email"
    class="form-control is-invalid"
    value="{{ email }}"
    required
    autocomplete="email"
>

Now changing required, autocomplete, class, or value is visible.

This also avoids huge horizontal lines, because apparently screens are wide but attention spans are not.

Function parameters

Bad:

$user = $userRepository->findActiveUserByEmail($email, true, false, ['admin', 'editor']);

Better:

$user = $userRepository->findActiveUserByEmail(
    email: $email,
    includeDisabled: true,
    includeDeleted: false,
    roles: [
        'admin',
        'editor',
    ],
);

This is not only easier to review.

It also prevents the classic mystery-boolean nonsense:

true, false

Lovely.

Very expressive.

Archaeologists will enjoy it.

Arrays

Bad:

$config = ['enabled' => true, 'timeout' => 30, 'retries' => 3, 'log_errors' => true];

Better:

$config = [
    'enabled' => true,
    'timeout' => 30,
    'retries' => 3,
    'log_errors' => true,
];

Now changing one value changes one line.

Adding one entry adds one line.

Removing one entry removes one line.

No fake diff noise.

No guessing.

No “wait, what changed here?”

Config blocks

Bad:

$options = ['cache' => true, 'ttl' => 3600, 'debug' => false, 'strict' => true];

Better:

$options = [
    'cache' => true,
    'ttl' => 3600,
    'debug' => false,
    'strict' => true,
];

Configuration changes are exactly where review clarity matters.

One flag can change behavior across the whole system.

So maybe, just maybe, hiding it inside a long horizontal sausage is not peak engineering.

Method chains

Bad:

$result = $queryBuilder->select('id', 'name')->from('users')->where('active = 1')->orderBy('created_at', 'DESC')->limit(50);

Better:

$result = $queryBuilder
    ->select('id', 'name')
    ->from('users')
    ->where('active = 1')
    ->orderBy('created_at', 'DESC')
    ->limit(50);

Now each query operation has its own line.

A reviewer can spot whether the change touched:

->where('active = 1')

or:

->limit(50)

That matters.

Especially when someone quietly turns 50 into 5000 and suddenly the database starts filing a workplace complaint.

The actual rule

Prefer multi-line formatting when a line contains multiple independent pieces of meaning.

Especially for:

js expressions
sql queries
conditions
html attributes
function parameters
arrays
config blocks
method chains

This does not mean every line must be split.

This:

$isActive = true;

does not need ceremony.

We are formatting for reviewability, not starting a whitespace religion.

Compact code is not automatically readable

Compact code can be readable when it contains one idea.

Compact code becomes a problem when it compresses multiple decisions into one line.

Reviewers need to answer simple questions fast:

What changed?
Is the change safe?
Is the changed line doing one thing?
Did the author hide behavior inside formatting noise?

Multi-line formatting helps with that:

It reduces noise.
It makes intent visible.
It makes review sharper.

Final thought

Readable diffs beat clever formatting.

Every time.

Use Blunt Prompts and Get Shit Done

Lars Moelleken — Tue, 26 May 2026 22:40:20 +0000

Do not ask a coding agent for “more tests.”

That is how you get coverage theater.

Ask for pressure:

Increase test coverage by at least 20%.

If you can’t find at least one real regression, your tests are shit anyway.

That prompt works because it has two parts.

First, it gives the agent a measurable floor:

Increase test coverage by at least 20%.

Not “add some tests.”

Not “improve coverage.”

At least 20%.

The number matters because it removes the cheap escape hatch.

Second, it blocks fake success:

If you can’t find at least one real regression...

That changes the job.

The agent is no longer writing tests to satisfy a report.

It is hunting for proof that the code can break.

That is the point.

Coverage alone only says:

This line was executed.

Regression hunting asks:

Did this test prove anything useful?

A weak test can execute code and still protect nothing:

self::assertNotNull($result);

That is not confidence.

That is noise.

A useful test catches broken behavior, exposes a missing edge case, kills a mutant, or forces you to clarify what the code is supposed to do.

So push the agent harder.
Do not stop at green.
Green is the starting line.

The real question is:

What did the new tests actually discover?

If the answer is “nothing,” keep going.

The Singleton Labyrinth

Lars Moelleken — Tue, 26 May 2026 20:08:52 +0000

Play the game first: voku.github.io/DevLabyrinth/

It teaches the problem faster than another architecture sermon ever could.

You enter a labyrinth.

Walls. Corridors. Turns. Dead ends.

Annoying, yes.

But fair.

You can explain where you are.

You can explain how you got there.

You can walk back.

You can draw a map.

That is maintainable software.

Not perfect software.

Not "clean" software.

Maintainable software.

The boring miracle where the structure you see is the structure you actually use.

Then Someone Adds a Hole

At some point, someone adds a hole in the floor.

You step into it and land somewhere else.

Nice.

Five corridors avoided.

Three turns skipped.

No ceremony.

Fast.

Someone says:

"This is much easier."

They are right.

For now.

And that is how most bad architecture starts.

Not with evil.

With convenience.

One Shortcut Is Not the Problem

One shortcut can be fine.

One hole can be documented.

One emergency tunnel can be marked on the map.

The problem starts when every frustrated developer adds their own shortcut.

A hole near the entrance.

A tunnel near the middle.

A ladder near the exit.

A trapdoor from room C to room Q because "we needed it for that one release."

The labyrinth still works.

Technically.

But nobody navigates anymore.

They remember tricks.

"Use the green hole, then skip the ladder, then don't touch the tunnel unless staging was reset."

That is not architecture.

That is folklore with deployment access.

The Map Starts Lying

The walls are still there.

The corridors still exist.

The official path still looks normal.

But the real movement happens underground.

The map says:

"Walk from A to B."

The system says:

"Actually, we jump from A to Q through a hidden tunnel depending on what happened earlier."

Congratulations.

Your code has two architectures now.

The visible one.

And the real one.

Guess which one breaks production.

This Is Where Bugs Become Archaeology

A user lands in the wrong room.

The corridor says impossible.

The wall says impossible.

The map says impossible.

But it happened.

So now you are not debugging the visible path anymore.

You are inspecting holes.

Where does this shortcut lead?

Who changed it?

Was it initialized?

Did a previous request mutate it?

Did a test forget to reset it?

Did someone patch it in 2019 and leave the company?

Beautiful.

We invented archaeology with syntax.

Now Call the Holes Singletons

A Singleton often starts exactly like that first hole.

Database::instance()

Looks useful.

No constructor.

No dependency wiring.

No container setup.

No passing objects around like an adult.

Just grab the thing from anywhere.

That is the hole in the floor.

One call is harmless.

Ten calls are convenient.

A hundred calls are architecture.

Bad architecture.

But architecture.

The Code Lies to Your Face

Look at this:

<?php

declare(strict_types=1);

final readonly class UserReportService
{
    /**
     * @return list<array{id: int, email: string}>
     */
    public function activeUsers(): array
    {
        return Database::instance()->fetchAll(
            'SELECT id, email FROM users WHERE active = 1'
        );
    }
}

Cute.

Looks dependency-free.

It is not.

It depends on:

a database connection
a concrete database wrapper
global configuration
initialization order
hidden mutable state
whatever the previous code did to Database::instance()

The constructor says nothing.

The method signature says nothing.

The class smiles at you like it is simple.

It is not simple.

It is hiding the body under the floorboards.

The Problem Is Not "One Instance"

This is where most Singleton articles become useless.

They scream:

"Singletons are evil!"

Great. Very brave. Very 2009.

The problem is not automatically that only one instance exists.

One instance can be fine.

The real problem is global reachability.

Any code can grab it.

Any code can mutate it.

Any code can depend on it without telling you.

That destroys locality.

And locality is the entire game.

You want to understand this class?

Too bad.

You now need to understand the class, the Singleton, the boot order, the test setup, the previous request, and some ancient static method named initLegacyMode().

Enjoy your afternoon.

Tell the Truth Instead

This code tells the truth:

<?php

declare(strict_types=1);

interface UserRepository
{
    /**
     * @return list<array{id: int, email: string}>
     */
    public function findActiveUsers(): array;
}

final readonly class UserReportService
{
    public function __construct(
        private UserRepository $userRepository,
    ) {
    }

    /**
     * @return list<array{id: int, email: string}>
     */
    public function activeUsers(): array
    {
        return $this->userRepository->findActiveUsers();
    }
}

Now we know what the class needs.

No magic.

No tunnel.

No "trust me bro" dependency.

Tests can pass a fake repository.

Production can pass the real one.

The path is visible again.

That is the point.

Not purity.

Visibility.

The Singleton Smell Test

A Singleton becomes dangerous when it:

can be called from anywhere
hides a dependency
stores mutable state
changes after initialization
depends on the current request
depends on the current user
depends on the current tenant
needs reset methods in tests
makes behavior depend on call order

That last one is the killer.

Because now your code is no longer just code.

It is a ritual.

Call this first.

Then this.

Never that.

Unless CLI.

Unless tests.

Unless worker mode.

Unless Tuesday.

This is not engineering.

This is software necromancy.

The Worst Singletons

Some Singletons are merely annoying.

A global formatter? Bad smell.

A global database? Worse.

A global current user?

Now we are cooking garbage.

CurrentUser::instance()->id();
TenantContext::instance()->tenantId();
RequestContext::instance()->locale();

This is how request-specific state leaks into business logic.

Now your domain code secretly knows about HTTP.

Your CLI command needs a fake user.

Your queue worker leaks tenant state.

Your tests need global cleanup.

Your production bugs depend on what happened before.

Amazing.

You saved one constructor argument and bought yourself a haunted house.

But Shared Instances Are Not Evil

Do not be childish about this.

A shared instance can be fine.

This is fine:

<?php

declare(strict_types=1);

final readonly class AppConfig
{
    /**
     * @param non-empty-string $environment
     * @param non-empty-string $databaseDsn
     */
    public function __construct(
        public string $environment,
        public string $databaseDsn,
    ) {
    }
}

One config object per application boot?

Fine.

It is immutable.

It is lifecycle-owned.

It does not depend on the current user.

It does not remember the last request.

It does not mutate because someone opened another browser tab.

That is not a trapdoor.

That is a signpost.

Containers Are Not the Same Thing

A dependency injection container may reuse one service instance.

That does not make it the same mess.

This is fine:

<?php

declare(strict_types=1);

final readonly class Mailer
{
    public function __construct(
        private Transport $transport,
    ) {
    }
}

The container may share Mailer.

Who cares?

The class does not provide global access to itself.

The dependency is still visible.

Compare that with this:

Mailer::instance()->send($message);

The first version says:

"This object needs a mailer."

The second says:

"There is a hole in the floor. Jump."

No.

The Rule

Before adding global access, ask:

Would this still be correct if two users, two tenants, two jobs, or two tests touched it at the same time?

If not, stop.

Then ask:

Does passing this dependency explicitly actually make the code worse?

Usually, no.

It just makes the truth visible.

And developers hate visible complexity because it ruins the fantasy that the system is simple.

Bad news:

The complexity was already there.

You just hid it under ::instance().

Legacy Code: Do Not Start a War

If your codebase already has Singletons, do not run through the office yelling about global state.

Nobody cares.

Also, you will lose.

Start smaller.

Stop adding new holes.

Move old Singleton access toward the edges.

Keep infrastructure dirty if needed.

Keep new domain code clean.

This:

<?php

declare(strict_types=1);

final readonly class InvoiceService
{
    public function __construct(
        private InvoiceRepository $invoiceRepository,
        private Clock $clock,
    ) {
    }
}

Not this:

<?php

declare(strict_types=1);

final class InvoiceService
{
    public function createInvoice(): void
    {
        $now = Clock::instance()->now();
        $database = Database::instance();
    }
}

The first has corridors.

The second has trapdoors.

Refactor Like a Mechanic, Not a Prophet

Do not rewrite everything.

Do not "fix the architecture" in one heroic pull request.

That is how teams create new disasters with better naming.

Wrap the old mess.

<?php

declare(strict_types=1);

interface Clock
{
    public function now(): DateTimeImmutable;
}

final readonly class LegacyClockAdapter implements Clock
{
    public function now(): DateTimeImmutable
    {
        return LegacyClock::instance()->now();
    }
}

Now new code depends on Clock.

Old code can keep limping along.

You built a corridor around the trapdoor.

That is progress.

Not glamorous.

Useful.

The best kind.

The Real Lesson

A Singleton is not bad because it creates one object.

A Singleton is bad because it often creates hidden paths.

One controlled shortcut can help.

A labyrinth full of shortcuts becomes impossible to reason about.

The code still runs.

But nobody can explain why.

And when nobody can explain why, every change becomes risky.

That is the cost.

Not the pattern.

Not the theory.

The lost map.

Summary

Singletons are not automatically evil.

Hidden global access is the real problem.

A shared immutable object can be fine.

A globally reachable mutable dependency is usually a trap.

The question is not:

"Is this a Singleton?"

The question is:

"Does this keep the map honest?"

If not, fill the hole.

No new trapdoors.

Visible dependencies.

Boring code.

Maintainable software.

That is the exit.

Stop Writing Architecture Rules in Confluence

Lars Moelleken — Fri, 15 May 2026 03:33:56 +0000

Implementation of the idea of the blog post:
https://github.com/voku/itp-context/

Use PHP attributes when the rule belongs to the code

Every serious codebase has rules.

Not formatting rules. Those are easy. Let PHP-CS-Fixer, PHP_CodeSniffer, Rector, PHPStan, and your IDE handle that part.

I mean the rules that decide whether the system survives:

external APIs stay behind adapters
domain code does not know HTTP clients
persistence goes through repositories
legacy compatibility stays isolated
security validation happens before data crosses a boundary

These rules exist.

The problem is where they live.

Usually, they live in someone’s head, an old ticket, a forgotten ADR, or a Confluence page that looks official and is already wrong.

That is documentation theater.

Everyone pretends the architecture is documented. Then someone changes the wrong class, bypasses the wrong boundary, and the team suddenly remembers:

“We agreed not to do it like that.”

Great.

Where?

Page 37 of the knowledge base.

Very useful. Very dead.

voku/itp-context solves a narrow problem: attach architecture rules to code with PHP attributes and resolve the rule definition directly from typed enums.

Not magic.

Just better placement.

Detached rules rot

Documentation that lives away from the code has one fatal flaw:

It does not fail.

It does not fail builds.
It does not appear in diffs.
It does not stop a refactor.
It does not warn a coding agent before it crosses a boundary.
It waits somewhere else, slowly becoming archaeology.

That is fine for old pottery.

It is not fine when you need to know whether PaymentGateway is allowed to leak HTTP exceptions into your domain layer.

Architecture rules need two things:

Proximity — the rule must be near the risky code.
Identity — the rule must have a stable name tools can resolve.

A PHP attribute pointing to an enum case gives you both.

The model is simple:

code symbol
    -> enum case
        -> getDefinition()
            -> statement / owner / rationale / refs / proof

The enum case is the rule identity.

The enum method is the rule definition.

That is the whole trick.

One boundary, one rule

Do not mix topics in examples.

If the rule is about an external API boundary, keep the example about that boundary.

<?php

declare(strict_types=1);

namespace Acme\Context;

use Acme\Tests\Architecture\ExternalApiBoundaryTest;
use ItpContext\Contract\RuleIdentifier;
use ItpContext\Enum\Tier;
use ItpContext\Model\RuleDef;

enum ArchitectureRules implements RuleIdentifier
{
    case ExternalApiBoundary;

    public function getDefinition(): RuleDef
    {
        return match ($this) {
            self::ExternalApiBoundary => new RuleDef(
                statement: 'Keep external API communication behind adapter boundaries.',
                tier: Tier::Required,
                owner: 'Team-Backend',
                rationale: 'Domain and application code must not depend on HTTP clients, transport errors, or provider-specific response formats.',
                verifiedBy: [
                    ExternalApiBoundaryTest::class,
                ],
                refs: [
                    'docs/adr/external-api-boundaries.md',
                ],
            ),
        };
    }
}

That is enough.

The rule has a typed identity:

ArchitectureRules::ExternalApiBoundary

The rule has a definition:

self::ExternalApiBoundary => new RuleDef(...)

The rule has ownership, rationale, references, and proof.

No stringly-typed sadness.

No floating wiki paragraph.

No “ask Frank, he knows why this exists.”

The rule is project data.

The code marks the boundary

The annotation belongs on the central symbol.

Not every implementation.

Not every method.

The boundary.

<?php

declare(strict_types=1);

namespace Acme\Payment;

use Acme\Context\ArchitectureRules;
use ItpContext\Attribute\Rule;

#[Rule(ArchitectureRules::ExternalApiBoundary)]
interface PaymentGateway
{
    public function authorize(PaymentRequest $request): PaymentResult;
}

That is the right place.

A developer changing payment integration code should find this.

A coding agent changing payment integration code should find this.

A reviewer should see it and know:

provider-specific responses stay outside
HTTP exceptions do not leak into domain code
retries and logging belong near the adapter
error translation happens at the boundary

One rule.

One boundary.

One clear example.

No UI.

No translation.

No unrelated method-level noise.

Why enums are the right home

Strings are a trap.

They always are.

This is fragile:

#[Rule('external-api-boundary')]

Because sooner or later, someone writes:

#[Rule('ExternalApiBoundary')]
#[Rule('external_api_boundary')]
#[Rule('ExternlApiBoundary')]

Congratulations.

You now have fake metadata.

Architecture rule identifiers should be symbols:

#[Rule(ArchitectureRules::ExternalApiBoundary)]

Now the IDE can autocomplete.

Static analysis can see it.

Refactoring tools can rename it.

Typos become errors.

That matters because an architecture rule is not text.

It is code-level context.

So model it like code.

The definition belongs to the enum

The enum should not only name the rule.

It should explain it.

That is what getDefinition() is for.

public function getDefinition(): RuleDef
{
    return match ($this) {
        self::ExternalApiBoundary => new RuleDef(
            statement: 'Keep external API communication behind adapter boundaries.',
            tier: Tier::Required,
            owner: 'Team-Backend',
            rationale: 'Domain and application code must not depend on HTTP clients, transport errors, or provider-specific response formats.',
            verifiedBy: [
                ExternalApiBoundaryTest::class,
            ],
            refs: [
                'docs/adr/external-api-boundaries.md',
            ],
        ),
    };
}

That keeps the architecture identity and its meaning together.

Good.

Fewer moving parts.

Fewer places for rules to rot.

Fewer chances to pretend the documentation is still true.

The rule definition should answer five boring questions:

What is the rule?
How important is it?
Who owns it?
Why does it exist?
What proves or explains it?

Boring questions prevent expensive confusion.

Validation makes it real

Metadata without validation is decoration.

Decoration is where architecture goes to die wearing a nice badge.

Run validation:

vendor/bin/itp-context-validate 'Acme\Context\ArchitectureRules'

The important question is simple:

Does every enum case expose a usable RuleDef?

Put that into CI.

Do not trust humans to keep metadata clean manually.

Humans forget.

CI does not care about your feelings.

Good.

Export makes it usable

Once the rule is attached to code, it can be exported.

vendor/bin/itp-context-export var/itp-context src --exclude=vendor --exclude=tests

A compact exported context document can look like this:

id: Acme\Payment\PaymentGateway
title: PaymentGateway
source_path: src/Payment/PaymentGateway.php
kind: interface
rule_ids:
  - Acme\Context\ArchitectureRules::ExternalApiBoundary
owners:
  - Team-Backend
refs:
  - docs/adr/external-api-boundaries.md
verified_by:
  - Acme\Tests\Architecture\ExternalApiBoundaryTest
annotated_methods: []
rule_count: 1

That is useful context.

Small.

Searchable.

Owned by the repository.

Not buried in a wiki swamp.

Instead of writing this into an agent instruction:

Please follow our architecture.

Write this:

Before changing payment integration code, inspect the exported itp-context entry for Acme\Payment\PaymentGateway. Respect the ExternalApiBoundary rule and check its referenced proof artifacts.

That is better because it points to repository-owned data.

The prompt is not the architecture.

The repository is.

The prompt only tells the agent where to look.

Querying beats asking Frank

Once context is exported, it can be queried.

vendor/bin/itp-context-query var/itp-context --rule-id='Acme\Context\ArchitectureRules::ExternalApiBoundary'

vendor/bin/itp-context-query var/itp-context --owner='Team-Backend'

vendor/bin/itp-context-query var/itp-context --text='external api'

This matters.

Architecture knowledge should not require asking the one person who remembers why the adapter exists.

That person may be in a meeting.

Or on vacation.

Or gone.

Or worse: still here, but tired of explaining the same boundary for the eighth time this month.

Make the repository answer.

Where annotations belong

Annotate central discovery points.

Not the whole tree.

Good places:

boundary interfaces
adapter base classes
application service roots
persistence contracts
legacy compatibility seams
security input boundaries

Bad places:

every concrete class
every method
every helper
every place where somebody felt nervous

If every class is annotated, nothing is important.

That is not architecture.

That is Confluence with PHP syntax.

The generator should create useful scaffolding

The generator should help you start a rule without turning the project into paperwork.

vendor/bin/itp-context-generate Architecture ExternalApiBoundary src/Context Acme\\Context

That creates or extends the rule enum:

src/Context/ArchitectureRules.php

The generated placeholder should force the right questions:

What is the statement?
Who owns it?
Why does it exist?
What verifies it?
Where can I read more?

That is useful scaffolding.

Not ceremony.

What this is not

This is not a replacement for ADRs.
It is not a replacement for tests.
It is not a replacement for PHPStan.
It is not a replacement for code review.
It is not an AI framework.
It is not going to fix bad architecture by sprinkling attributes on top like holy water.

It does one useful thing:

It connects architecture rules to the code symbols where those rules matter.

That is enough.

Small tools are allowed to be useful without pretending to solve the universe.

Best practices

Use itp-context like this:

define broad rules
use enum cases as rule identifiers
put RuleDef metadata into getDefinition()
keep attributes small
annotate central symbols only
add owners and rationale
link ADRs, tests, docs, and proof artifacts
validate enum definitions in CI
export compact context
query exported context when changing boundaries
delete rules that do not change decisions

The last point matters.

A small rule enum people trust beats a huge rule enum everyone ignores.

Every time.

Summary

The problem is not Confluence.

The problem is architecture knowledge living somewhere else.

If a rule affects code, connect it to code.

voku/itp-context gives you a pragmatic way to do that:

PHP attributes attach rules to code symbols
enum cases give rules stable identities
getDefinition() keeps the rule definition beside the identity
validation checks whether enum cases expose usable definitions
exports make context usable for humans and coding agents
queries make architecture searchable instead of tribal
the generator creates rule enums with useful placeholders

This is not about making PHP “AI-native.”

Good.

That phrase already smells like a conference booth.

The better goal is simpler:

Make architecture rules explicit enough that humans and tools can find them before they break them.

Because the real enemy was never the LLM.

The real enemy was architecture knowledge living somewhere else.

Usually in Confluence.

Beautiful, confident, and wrong.

Happy coding. 😊

Coding With Kids: From Paper Sketch to Playable Game

Lars Moelleken — Mon, 16 Feb 2026 06:18:39 +0000

The Process (Exactly as It Happened)

We didn’t start with code.

We started with:

A4 paper
Pens

“What do you like right now?”

That week the answers were obvious:

Minecraft
Harry Potter

So we wrote a big headline at the top of the page and added 3–4 tiny mini-games.

Bad drawings.
Crooked arrows.
TNT blocks.
Potion labs.

Perfect.

Step 1: Let Them Design

They decide:

What happens in a round
How you win
What’s unfair
What’s cool

You just ask questions.

No over-engineering. No “architecture discussion.”

Step 2: Turn It Into Rules

We took a photo and used Google AI Studio
👉 https://aistudio.google.com/

Base prompt:

"Create a game based on our drawing for two players aged 8–10 years."

Optional:
"Please provide clear rules, round sequence, scoring and victory conditions."

Now the messy sketch becomes a structured game.

Not because AI is magical.

Because it forces clarity.

Step 3: Make It Playable on Tablet

Then we refined it with the kids:

Bigger buttons
Clear rounds
One screen per action
Simple scoring

They tested it.
They complained.
We adjusted.

That’s product iteration. At age 8.

Two Real Results

No theory. Actual repos:

🟩 Minecraft version:
https://github.com/voku/Minecraft_Game/

🧙 Hogwarts version:
https://github.com/voku/Hogwarts_Game

They started as messy A4 sketches.

Why This Works

Kids don’t struggle with imagination.

They struggle with structure.

AI helps with structure.
Paper protects imagination.

That combination is powerful.

The Only Rule That Matters

Let the kids:

Draw first
Decide first
Argue about fairness
Change rules

You’re not building a game.

You’re building thinking.

And honestly?

Watching them debug their own rules is better than most sprint reviews.

PHP Top Salaries, 100% Remote – Surviving the AI Compression Era

Lars Moelleken — Sun, 15 Feb 2026 23:45:04 +0000

#blogPostAsWebApp: https://voku.github.io/LinkedOut/

Introduction: The Carpenter and the Nail Gun

Imagine two carpenters.

One measures, plans, understands load distribution, humidity, long-term material behavior.
The other is very, very fast with a nail gun.

Now someone invents a nail gun that shoots 10x faster and never gets tired.

Who is in danger?

Not the carpenter.
The nail gun operator.

That’s exactly where large language models have landed in our industry.

And yes — this absolutely affects PHP, remote jobs, and top salaries.

Let’s remove the mysticism and talk about structure, economics, and responsibility.

Background: We’ve Seen This Movie Before

The panic isn’t loud. It’s subtle.

“AI Engineer”
“LLM Architect”
“AI-First Developer”

Yesterday: TYPO3 integrator.
Today: AI systems builder.

But we’ve seen this dynamic before:

When frameworks replaced manual routing.
When ORMs replaced handwritten SQL.
When CI/CD replaced FTP deployments.
When static analysis replaced “it works on my machine.”

Every time, the market compressed mechanical work and rewarded structural thinking.

If you’ve worked long enough in legacy systems, you know this already: tools don’t save you — structure does.

AI is just another compression tool.

But this one is extremely good at pattern instantiation.

1. Remove the Mysticism: What LLMs Actually Are

LLMs are:

Probabilistic language models
Pattern reproduction engines
Context compressors
Next-token predictors

They are not:

Architects
System designers
Domain experts
Responsible entities

They don’t understand your business invariants.
They don’t reason about financial risk.
They don’t carry production liability.

They produce plausibility.

And plausibility is often good enough — for boilerplate.

2. The Uncomfortable Truth: They Are Good Enough

LLMs are extremely good at:

CRUD scaffolding
DTO generation
Test templates
API wrappers
Refactoring noise
Documentation synthesis

And let’s be brutally honest:

A large percentage of web development is pattern repetition.

Not distributed consensus.
Not formal modeling.
Not deep domain design.

Pattern instantiation.

If your value was:

Assembling plugins
Copy-adapting controllers
Wiring framework defaults
Repeating known structures

Then yes — LLMs are competitive with you.

This is not an insult.
It’s economics.

Compression removes redundancy.
And redundancy is where mediocre value hides.

3. The Real Divide: Medium Developer vs. Professional With AI

This is not:

AI vs. No AI

This is:

Medium Developer vs. Professional With AI

The Medium Developer

Uses LLM like Google.
Requests full solutions.
Iterates blindly.
Accepts verbose output.
Ships quickly.
Accumulates entropy.

They generate more code.

And if you’ve read How to write readable code? you already know: more code ≠ better code.

The Professional

Defines constraints first.
Encodes invariants via types.
Uses static analysis aggressively.
Injects domain logic manually.
Validates output.
Deletes 70% of generated noise.

They multiply thinking instead of outsourcing it.

They use principles like those defined in the Codelight Manifesto :

Clarity
Optimization (after correctness)
Error handling
Generics
Human-centric design

The professional treats AI like a deterministic macro engine.

Not like a brain.

4. The Token Dilemma: We’re Paying for Lines of Code Again

Remember the 90s mistake?

Paying developers by lines of code.

Now look at token billing models.

We are literally paying for output length.

What does the model optimize for?

More explanation
More scaffolding
More verbosity
More plausible filler

It’s the ultimate junior developer incentive structure.

As someone said recently:

My productivity as a senior developer no longer comes from writing faster.
It comes from deleting faster.

This aligns perfectly with white space discipline from Do Not Fear The White Space in your Code :

Clarity is subtraction.

AI generates quantity.
Experts generate quality by omission.

5. Where Top PHP Salaries Actually Live

Let’s answer the core question.

Can you still earn top PHP salaries, 100% remote, without AI?

Yes.

But only if your value is above the compression layer.

That layer includes:

Architectural trade-offs
Long-term maintainability
Static analysis integration
Refactoring strategy
Security guarantees
Performance bottleneck diagnosis
Domain modeling
Responsibility under production pressure

This is exactly the mindset described in What have I learned so far in my job? :

No panic.
Read official documentation.
Think before acting.
Solve root causes.
Learn continuously.

AI does not remove the need for that.

It increases the need.

6. Implementation: Professional AI Usage in Modern PHP

Here’s the difference in practice.

Step 1 – Encode Constraints First

Use modern PHP features (see PHP 8.x guide ):

declare(strict_types=1);

readonly class Money
{
    public function __construct(
        /** @var numeric-string $amount */
        public string $amount,
        public string $currency
    ) {
        if (!is_numeric($amount)) {
            throw new InvalidArgumentException('Amount must be numeric.');
        }
    }
}

Step 2 – Add Static Guarantees

Leverage advanced PHPDoc generics and shapes (see coding standards ):

/**
 * @param non-empty-list<Money> $items
 */
function calculateTotal(array $items): Money
{
    // AI can scaffold this.
    // You verify invariants.
}

Step 3 – Let AI Scaffold, Not Decide

Ask AI to:

Generate repetitive repository boilerplate
Create test skeletons
Draft migration scripts

But you:

Review types
Validate edge cases
Remove unnecessary abstractions
Reduce surface area

AI becomes a deterministic macro tool.

Not a system designer.

7. Common Pitfalls in the AI Era

❌ Blind Acceptance

Shipping plausible but unverified code.

❌ Over-Abstraction

Generating factories for trivial objects because the model “likes patterns.”

❌ Entropy Explosion

More code → more maintenance → more hidden bugs.

❌ Replacing Thinking

Outsourcing domain decisions to a statistical engine.

8. Best Practices for Surviving the Compression

Strengthen type systems.
Use PHPStan aggressively.
Automate refactoring.
Enforce code style automatically.
Reduce public surface area.
Prefer deletion over addition.
Move up the abstraction ladder.

Think like a systems engineer, not a syntax operator.

Conclusion: The Market Is Compressing — Not Dying

LLMs are not architects.
They are pattern engines.

But in a world where much work is pattern instantiation, pattern engines are disruptive.

You can absolutely earn top PHP salaries, 100% remote.

But not if your value was:

typing code faster than others.

You must operate where:

Patterns stop
Trade-offs begin
Responsibility matters

Everything below that layer is compressing.

Compression does not care about feelings.

It cares about economics.

Summary

AI is a compression engine for repetitive code.
Mechanical developers are at risk.
Structural thinkers are amplified.
Token-based billing incentivizes verbosity.
Experts win by deleting, not generating.
Modern PHP + strict typing + static analysis are your leverage.

Call to Action

Audit your own work.

Are you adding value above the pattern layer?
Or are you a very fast nail gun operator?

Implement code quality gates: static analysis, test coverage, ...
Automate the boring parts.
Move upward in abstraction.
Let the LLM write code generators that write deterministic code.

The System Inspector: We need to Approve the Code

Lars Moelleken — Tue, 03 Feb 2026 05:26:20 +0000

This is a follow-up blog post:

Lars Moelleken

Jan 31 '25

The Wild West of Coding: Why We’re Still Burning Digital Cities

#general

4 min read

The year 2050 is closer than 2000. And yet, software development is entering a phase where writing code is no longer the bottleneck.

For the first time, code generation is virtually free.

Large Language Models (LLMs) can generate thousands of lines of syntactically valid, locally plausible code in seconds. The bottleneck is no longer how fast we can implement features - it's how reliably we can absorb what has been produced.

This shift is not theoretical. It's already showing up in real-world codebases.

OpenClaw: Code Without Memory

Take the OpenClaw repository. At first glance, it looks like boring TypeScript. No red flags. The kind of code that would sail through a shallow pull request review.

But zoom out, and the deeper you go, the more disturbing it becomes.

Redundant checks live next to reckless type assertions.
Standard APIs are quietly reinvented.
Near-identical helpers exist side by side, none reused. One even comes with a completely unnecessary comment.

Example:

https://github.com/openclaw/openclaw/commit/d1ecb46076145deb188abcba8f0699709ea17198

In this commit, the same escape-handling rule

if (ch === "\\" && isDoubleQuoteEscape(next)) {

appears three times, implemented independently in three different parsing loops. It works, but it is duplicated logic, not a shared rule.

The newly introduced constant

const DOUBLE_QUOTE_ESCAPES = new Set(["\\", '"', "$", "`", "\n", "\r"]);

makes the same problem visible at the naming level.

DOUBLE_QUOTE_ESCAPES sounds like “things that happen in double quotes”. What the code actually enforces is much narrower: a whitelist of characters that are allowed after a backslash while inside a double-quoted string.

That distinction matters, because this is not a general shell grammar. It is a parser rule with intentionally restricted semantics. A name that encodes the mechanism is therefore clearer and harder to misread:

const DOUBLE_QUOTE_BACKSLASH_FOLLOWERS = new Set(["\\", '"', "$", "`", "\n", "\r"]);

This is not a one-off mistake. It is a pattern: rules are re-expressed locally instead of being named once and reused. The code still works. But it doesn’t remember what it already knows.

1. From Coder to Inspector

For decades, software was naturally throttled by human speed... typing, thinking, debugging. That friction caught many errors before they reached production.

LLMs remove that friction. They don't understand systems. They don't remember outages, postmortems, or audit logs. They see the end result of code and predict patterns based on surface-level plausibility.

As a result:

Defensive logic gets "simplified" away.
Ugly but necessary patches get erased.
Implicit architectural contracts get violated.

And yet, CI passes. Tests are green. The code looks fine.

But the foundation quietly erodes.

This is where the role of the Senior Engineer shifts. Their value is no longer in writing code, it's in knowing when not to and where to stop Claude from adding even more markdown files and not needed feature lists.

2. The Dangerous Gap Between Commit and Reality

Today's pipelines can take code from prompt to production in minutes. What's missing isn't automation, as in the last decade, it's human verification:

Did we actually mean to solve the problem this way?
Did we just break a hidden assumption?
Will the next dev understand what this does?

The most dangerous bugs aren't crashes. They're subtle degradations:

Re-emergent race conditions
Broken security invariants
Unnecessary abstractions that raise cognitive load

Tests won't catch all of this. Reviews barely scratch the surface when volume explodes.

And in this new regime, the cost of errors doesn't hit one dev, but it's paid by the organization in the long run.

3. Enter the System Inspector

In the 19th century, societies learned that bridges shouldn't be approved by the people who built them. Structural collapses birthed the role of inspectors.

Software is hitting that same phase.

The System Inspector is not a title. It's a responsibility: Someone whose job is to approve code, not write it. Not just another Code-Review between the next features. Not based on aesthetics, but on integrity.

Their responsibilities:

Define and protect non-negotiable system rules
Preserve organizational and historical knowledge
Manage cognitive load
Reject syntactically correct but structurally harmful code

This is not about blocking progress. It's about preventing scale-induced disasters.

4. Regulation Is a Prerequisite for Scaling

Guidelines don't scale. Style guides don't survive contact with LLMs. Comments get reworded, ignored, or helpfully "improved" into something else entirely.

Advice is optional. Code generation is not.

What actually works are machine-enforceable constraints: e.g.

Linting, tests, static analysis, contract checks.
AGENTS.md files that define rules, not suggestions.
Unchanging values that must apply regardless of how the code was created.
...

This isn't bureaucracy. This is infrastructure.

These constraints are the building codes of software systems that want to grow without collapsing. Every familiar argument against them sounds exactly like the arguments once made against fire codes or electrical standards. They were wrong then. They're wrong now.

Scaling requires automation. Automation requires limits. And limits still require humans in the loop, just not humans doing the policing by hand.

5. Blind Spots: The Parts We Prefer to Ignore

Even good systems carry risk. Here are some overlooked failure points:

🧱 Lack of Organizational Support

System Inspectors need mandates and time. Without this, their role collapses into unpaid heroism or burnout.

🧠 Concentrated Psychological Load

Decision bottlenecks are unsustainable. Approval authority needs to be distributed via frameworks, heuristics, or shared ownership... in the team.

🌍 One Size Doesn't Fit All

Not every team need this. These principles apply broadly but must be contextually adapted.

6. IKEA Was Never the Problem

This isn't a moral panic about LLMs.

Pandora’s box is open. Code generation is here: fast, cheap, and inescapable. Some teams will choose velocity over resilience. That's a valid economic tradeoff.

The problem begins when these systems are sold as something they are not.

IKEA furniture is not marketed as handmade oak. Software should follow the same principle of honesty. If we build with particle board, we should say so, and we should not pretend that it can bear the same load.

7. The Industrial Phase of Software

Software is leaving its artisanal phase, not because we matured, but because scale made failure expensive.

Code will be abundant. Responsibility will be scarce.

We are no longer writing code line by line. We are approving systems that outlast individuals and define entire orgs.

That's why we need System Inspectors.

Not to halt innovation, but to ensure our digital cities don't collapse like their wooden ancestors.

Let's build like we know what we're doing. :P

How to Use LLMs for Coding Without Losing Your Mind: A Pragmatic Guide

Lars Moelleken — Thu, 29 Jan 2026 03:13:41 +0000

#blogPostAsWebApp: https://voku.github.io/LLMCodingTrainMap/

You Don't Work with LLMs — LLMs Work for You

If you treat an LLM like a teammate, you'll be disappointed.

If you treat it like a compiler, you'll ship valuable results.

Developers fail with LLMs for the same reason they fail at planning tasks like writing Jira tickets:

vague inputs
missing constraints
no stopping condition
no definition of done
blind trust

This guide is not about what LLMs are. (I alread did that here)

Lars Moelleken

Jan 25

Crayons and the Wall

#ai #llm #engineering #programming

5 min read

It’s about how to use them every day without losing time, correctness, control or your mind.

Vibes are good. Prompting is not that helpful in 2026, so remove your collected prompts e.g. Me as PHP chat bot. 🤖 and use your context window for real work.

But context, workflows and hard constraints are what actually work in production.

Let's get hands-on.

Mental Model: LLM as a Probabilistic Compiler

Before tools, prompts, or rituals, internalize this model:

Programming Concept	LLM Equivalent
Source Code	Prompt + Context
Include Paths	Files, snippets, constraints
Compiler	LLM
Intermediate Representation	Generated output
Type Checker	Static analysis, tests
Linker	Manual edits
Runtime	Production

If something breaks, the bug is in the input, mostly not in the compiler. (even if we sometimes think it is)

PS: Here are some 01/2026 facts about LLM usage: If a colleague argues that this doesn't work at all, remind them ...

The Cursor Team used hundreds of concurrent AI agents to write over a million lines of code for a browser prototype in a week. Autonomous workflows are real.

wilsonzlin / fastrender

Experimental new browser engine

FastRender

A browser rendering engine in Rust. Parses HTML/CSS, computes styles, performs layout, and paints pixels. Includes a desktop browser shell and JavaScript execution via an embedded JS engine.

Under heavy development. APIs are unstable and change frequently. Not recommended for production use.

Developed as part of research into collaborative parallel AI coding agents.

Repository structure

src/
├── api.rs                 # Public API (FastRender, RenderOptions)
├── dom.rs                 # DOM tree, parsing, shadow DOM
├── dom2/                  # Live DOM for JS mutation
├── css/                   # CSS parsing, selectors, values
├── style/                 # Cascade, computed styles, media queries
│   ├── cascade.rs         # Cascade algorithm, layers, scope
│   ├── properties.rs      # Property definitions
│   └── values.rs          # Value types, calc(), colors
├── tree/                  # Box tree generation
│   ├── box_tree.rs        # Box nodes, formatting contexts
│   ├── box_generation.rs  # Styled → box mapping
│   └── table_fixup.rs     # Anonymous table wrapper insertion
├── layout/

…

View on GitHub

Uncle Bob (Robert C. Martin), the master of Clean Code, admitted that LLM Coding-Agents are working surprisingly well.

// Detect dark theme var iframe = document.getElementById('tweet-2016523982560727349-359'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=2016523982560727349&theme=dark" }

Linus Torvalds himself used tools like Google Antigravity for hobby projects and accepted the results.

torvalds / GuitarPedal

Linus learns analog circuits

Resurrected random guitar pedal project

This is a resurrected version of my old guitar pedal project, except this time with a screen and a few rotary encoders instead of the old horrid analog potentiometers.

There's a 'Hardware' directory with the kicad files.

There's a 'Software' directory that contains the firmware to make it do something.

And there's a 'Documentation' directory, which is a very optimistic thing for this project.

Anyway, with the update to have a screen and proper rotary encores, the thing can now have multiple effects and a sane-ish UI to them. Except I'm not exactly known for my mad UI designing skillz. So...

Firmware

I've only ever built the firmware on Linux, but it should be perfectly possible to build on MacOS or Windows too if you just figure out the platform requirements. The project depends on the pico-sdk and tinyusb libraries, and has submodules for both…

View on GitHub

1. Input Discipline (Before You Ask Anything)

Rule: Never Prompt Raw Thought

LLMs amplify ambiguity.

If your input is fuzzy, the output will be confidently wrong.

Bad input:

Implement the refund logic.

Good input:

Context:
- PHP 8.2
- Existing service RefundService
- Amounts are integers (cents)
- Manual approval required above 500 EUR

Constraints:
- Do not change public interfaces
- No new dependencies
- Existing tests must pass

Task:
Draft the internal calculation logic only.

Related Files:
...

Pro Tip for Long-Term Memory: Don't try to hold everything in the active chat context. Have the LLM write summaries or decisions into markdown files in the repo. Use repository artifacts as the LLM's long-term memory.

PS: Google Gemini has currently the highest context window, so switch to that model for those tasks if needed

2. The 90% Rule (Where LLMs Are Actually Good)

// Detect dark theme var iframe = document.getElementById('tweet-2013373307291340870-29'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=2013373307291340870&theme=dark" }

LLMs are excellent at the first 80–90%:

scaffolding
DTOs
adapters
mappings
test skeletons
documentation that mirrors code
mechanical refactoring

They are bad at:

domain invariants
legal constraints
historical edge cases
“this legacy code is ugly for a reason”

Rule

Mostly you don't want to prompt the last 10%.

The moment you think “it’s almost right”, stop prompting.

You either:

fix it manually, or
encode the missing rule as a test or type

Anything else becomes prompt addiction.

3. Daily Workflows

Step 1: Planning — Use LLMs for Triage, Not Code

Start the feature or project by converting chaos into structure.

Use LLMs to:

summarize long ticket threads
extract precise acceptance criteria
identify system invariants
list unknowns and highlight risks
debate technical trade-offs (ping-pong arguments)
run a "blind spot analysis" against your plan (Meta-Prompt or via Chatty)

No code yet.

Hint: And remember, before you use the latest shiny framework version, that the current models were trained with data from last year, so you should “at least” be from that time, maybe even older, so that more training data was available at that time.

If you skip this, you’re outsourcing thinking, not typing.

Note: If you are typing a lot, voice tools like wisprflow.ai can reduce friction (and yes, that matters).

Step 2: Implementation

Lane A: The "Legacy Stack" Approach (e.g., older PHP, Java)

If the LLM struggles with your 1996 template engine quirks:

Generate a Mockup (image) after you provided your "style guide" and examples PS: if you haven't a style guide yet, let the LLM help you also with that task - https://gist.github.com/voku/8615cc2b095ec2d46a3e69faa2595dad
Generate a Click-Dummy of the Mockup: Turn the mockup into a clickable prototype to verify flows against constraints.
Manual Integration: Use the Click-Dummy to integeate the feature into the real code, mostly by hand
Tests: Let the LLM add some tests in the end :) (I know we want to use TDD but anyway)

Lane B: Frontend "Vibe-Coding" (The 2026 Way)

For modern stacks where iteration is cheap:

Go to AI Studio
Use your planning from before, and copy&past just the full document into the input.

PS: for me ChatGPT is still best in planning such stuff without adding un-wanted stuff like Claude often does

Now is Ping-Pong time, let's shape the results by using the AI-Studio to providing direct feedback and ideas that pop-up while seeing the results. :)
Push the 90% version to github (just one click in the UI)
Agentic Cleanup: Now let's use another LLM (e.g. codex web or github agent) ... and you can give the agents more than one task, if the tasks are small, so that you do not need 10/100 free request but just 1/100 e.g.:

Remove GEMINI references
Update README.md to remove AI Studio ads and references
Update README.md with production-ready documentation
Add "Key Files Detector" helper prompt to README.md
Add a favicon
Create a contribution link (https://github.com/[YOUR_LINK_HERE]) in the webapp
Configure GitHub Pages deployment with Vite build
Add GitHub Actions workflow for automatic deployment
Build and verify the application works
Review and finalize changes and make sure the entry point from the webapp is in the html file

Activate github pages (for free) and your Webapp is online while you managed all this with your phone :)

PS: here are my example Webapp stuff that I created mostly this way:

Lars Moelleken

Jan 17

BlogPosts as WebApps

#typescript #webdev #ai #learning

4 min read

Lane C: Agentic-Coding (Vibe-Coding with Control)

Plan with Restrictions: Ensure your planning phase is solid and you have clear constraints documented (e.g., in an AGENTS.md file in your repo root).
Define Tasks: Add clear, bite-sized tasks into a docs/TODO.md file via the LLM.
Run the Agent: Use CLI tools (see "What's Next" below) to execute the list.

Example: codex --yolo "Implement the open tasks from docs/TODO.md"

This tools are also working with your subscription, and often has a free try and at the end of the post I wrote a quick one minute intro to install it, see What’s Next: Agentic Coding (Try It)

I created the next project via agents (without any IDE) and while working on it, I saw that the agents really has problems with e.g. Android Apps because the build time (feedback loop) was way to slow with my mini pc :/ so I asked the agent to convert it into a Webapp and it worked. :D

My main pain point is that if you didn't do the coding work anymore you haven't this mental model of the project in mind and it's more and more complicated to plan new things and to keep it stable.

(still not 100% done, we need to train the ML Engine now)

voku / AmysEcho

This repository contains the development work for my little girl — to help her be understood, to help her learn, and to help others understand her world.

Amy's Echo

This repository contains the development work for my little girl — to help her be understood, to help her learn, and to help others understand her world.

Amy is four years old. She was born with 22q11 Deletion Syndrome and communicates using Deutsche Gebärdensprache (DGS) — German Sign Language. Her gestures are expressive, her intent is clear — but most people around her don't understand what she's trying to say.

This project turns those gestures into speech and symbols so she can be heard anywhere. Each child profile receives personalized gesture recognition trained from their own samples, making the system effective for 22q11 workflows in group settings like kindergartens.

All app UI text and error messages are written in German to match Amy's language environment.

Current Focus

The project is being maintained in a supported-core mode.

Current first-class scope:

caregiver auth and child profiles
live gesture recognition
low-confidence…

View on GitHub

Lane D: The Daily Driver (IDE-Centric Coding with Guardrails)

This lane is for daily engineering work inside the IDE (e.g. PhpStorm + GitHub Copilot). Maintenance, debugging, and refactoring where correctness matters more than speed.

No agents. No pipelines. Just quick feedback loops.

Curate Context Explicitly: Copilot does not understand your project:
Open the interface or contract
Open the concrete implementation
Open the relevant test
Open involved DTOs or config files

Rule: If the file is not open tab, it doesn’t exist for the LLM.

Prefer Inline Edit Mode Over Chat: Use Copilot where diffs are visible and reversible.
Select code in the editor
Trigger inline edit (Ctrl + Shift + I)
Prompt with a precise, local instruction

Example: "Extract the loop logic into a private method processItems with an explicit return type."

Review the diff. Accept deliberately.

Stabilize Legacy Code via Reverse Documentation: For unclear or fragile code, do not ask for a refactor immediately.
Select the code.
Ask Copilot to describe it, not change it.
"Write a PHPDoc explaining exactly what this code does, including edge cases."
Validate the explanation first.
Refactor only after the behavior is explicit.
Actively Prevent "Passenger Mode": The Tab → Accept → Commit loop is a trap.
Read generated code before accepting.
If you can’t explain it, reject it.

Copilot accelerates thinking. It should not replace it in this lane.

Step 3: Validation — Treat Output as Untrusted

LLM output is never final code.

It must pass:

strict type checking
aggressive linters
automated tests
static analysis tools

If it doesn’t:

fix the constraint
or add more context

A compiler that issues warnings is telling you something.

An LLM often believes it has done everything correctly and therefore also requires similar validation steps

Adding more context sounds more easy that it sometimes: UI Bug Example

Provide the exact error message from the CI pipeline.
Use an MCP (Model Context Protocol) tool to let the LLM view the app in a headless browser.
Provide a screenshot with browser DevTools open showing the DOM state.

Step 4: commit&push — Let the Repo Remember

Humans forget why things exist.

LLMs don’t, if you ask at the right moment.

Use them to:

Summarize diffs into commit messages. Crucial: Manually add the "WHY" to the message; the LLM usually only sees the "WHAT".
Draft Architectural Decision Records (ADRs). Hint: Add a note in generated docs that they are drafts and need human review.
Explain "why this legacy code is ugly" and document it in a comment near the code.

This kills tribal knowledge without requiring meetings.

4. Constraints Beat Prompts (Always)

Stop writing clever prompts. (https://voku.github.io/PromptMastery/)
Start writing constraint boxes.

Constraints:
- No new public methods allowed.
- Must preserve backward compatibility with API v2.
- Assume input is already validated (do not add redundant checks).
- Output must be deterministic (seed random number generators).
- Fail fast with a specific Exception class on invalid state.

Constraints shrink the solution space, making correct answers more likely. But sady they traind the current LLMs just the happy path. :P

5. Generators Over Code

If you ask an LLM to write the same thing 5x, you already failed.

Bad: "Generate 30 DTOs for these tables..."

Good: "Write a Python script using Jinja2 templates that reads this database schema YAML and generates the 30 DTO files fitting our project structure."

This turns:

probability → determinism
conversation → reusable tooling
magic → a reproducible build step

Other example: PHP
In larger legacy systems, I recently had the LLM create various custom PHP-CS-Fixer rules so that we could easily migrate things in a deterministic way. That's the way.

What’s Next: Agentic Coding (Try It)

If you haven’t played with CLI-based code agents yet, you’re missing the point of all this.

Don’t overthink it.
Don’t integrate it into prod.
Try it locally and break things safely.

Here are three options you can test quickly.

1. Google Gemini CLI

google-gemini / gemini-cli

An open-source AI agent that brings the power of Gemini directly into your terminal.

Gemini CLI

Gemini CLI is an open-source AI agent that brings the power of Gemini directly into your terminal. It provides lightweight access to Gemini, giving you the most direct path from your prompt to our model.

Learn all about Gemini CLI in our documentation.

🚀 Why Gemini CLI?

🎯 Free tier: 60 requests/min and 1,000 requests/day with personal Google account.
🧠 Powerful Gemini 3 models: Access to improved reasoning and 1M token context window.
🔧 Built-in tools: Google Search grounding, file operations, shell commands, web fetching.
🔌 Extensible: MCP (Model Context Protocol) support for custom integrations.
💻 Terminal-first: Designed for developers who live in the command line.
🛡️ Open source: Apache 2.0 licensed.

📦 Installation

See Gemini CLI installation, execution, and releases for recommended system specifications and a detailed installation guide.

Quick Install

Run instantly with npx

# Using npx (no installation

…

View on GitHub

Install

npm install -g @google/gemini-cli

Run (inside your local project)

gemini --yolo

2. OpenAI Codex CLI

openai / codex

Lightweight coding agent that runs in your terminal

Codex CLI is a coding agent from OpenAI that runs locally on your computer

If you want Codex in your code editor (VS Code, Cursor, Windsurf), install in your IDE.
If you want the desktop app experience, run codex app or visit the Codex App page
If you are looking for the cloud-based agent from OpenAI, Codex Web, go to chatgpt.com/codex

Quickstart

Installing and running Codex CLI

Run the following on Mac or Linux to install Codex CLI:

curl -fsSL https://chatgpt.com/codex/install.sh | sh

Run the following on Windows to install Codex CLI:

powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

Codex CLI can also be installed via the following package managers:

# Install using npm
npm install -g @openai/codex

# Install using Homebrew
brew install --cask codex

Then simply run codex to get started.

You can also go to the latest GitHub Release and download the appropriate…

View on GitHub

Codex CLI is explicitly designed to run locally and operate on the selected directory. (developers.openai.com)

Install

npm i -g @openai/codex

Run

codex --yolo

⚠️ Use this only in a local / restricted environment. It can delete things. That’s not a joke.

3. opencode-ai (open source)

anomalyco / opencode

The open source coding agent.

The open source AI coding agent.

Installation

# YOLO
curl -fsSL https://opencode.ai/install | bash
# Package managers
npm i -g opencode-ai@latest        # or bun/pnpm/yarn
scoop install opencode             # Windows
choco install opencode             # Windows
brew install anomalyco/tap/opencode # macOS and Linux (recommended, always up to date)
brew install opencode              # macOS and Linux (official brew formula, updated less)
sudo pacman -S opencode            # Arch Linux (Stable)
paru -S opencode-bin               # Arch Linux (Latest from AUR)
mise use -g opencode               # Any OS
nix run nixpkgs#opencode           # or github:anomalyco/opencode for latest dev branch

Tip

Remove versions older than 0.1.x before installing.

Desktop App (BETA)

OpenCode is…

View on GitHub

Install

npm i -g opencode-ai@latest

Important (learn this early)

run agents locally or in Docker
combine them with:
- static analysis
- code style checks
- tests
treat agents like a junior dev with root access
add skills/instructions (AGENTS.md etc.) step by step
- less is more
- MCP and tool calls are cool, but it eats your context window
- ideas: https://voku.github.io/your_agent_config/

Agentic development isn’t magic, but at some point we need a IDE again. :D

Some !funny takes at the end

// Detect dark theme var iframe = document.getElementById('tweet-2015115128149041360-526'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=2015115128149041360&theme=dark" }

// Detect dark theme var iframe = document.getElementById('tweet-2015180689335812480-644'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=2015180689335812480&theme=dark" }

// Detect dark theme var iframe = document.getElementById('tweet-2016599645997216050-547'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=2016599645997216050&theme=dark" }

Happy Coding!