DEV Community: Lars Moelleken

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
Demo: https://voku.github.io/agent_loop_demo/

Your Coding Agent Doesn’t Need More Memory. It Needs a Governed Loop.

Coding agents repeat mistakes.

The obvious response is to give them more memory:

MEMORY.md
project-rules.md
agent-notes.md
lessons-learned.md
MEMORY_FINAL.md

Soon the agent receives old decisions, temporary workarounds, copied transcripts, abandoned ideas, and rules nobody remembers approving.

It has more context.

It does not necessarily have better context.

At some point, memory becomes landfill.

The problem is not that coding agents forget too much.

The problem is that most workflows fail to distinguish between temporary context, evidence, proposed learning, and approved project guidance.

A transcript is not memory.
A note is not a rule.
A finding is not guidance.
And a successful patch is not automatically a project convention.

Instead of giving the agent one growing pile of context, I built "voku/agent-loop" around a governed workflow:

task
-> candidate plan
-> human approval
-> selective recall
-> implementation
-> verification
-> recorded evidence
-> reviewed learning

The important detail is that the developer does not normally operate this workflow by typing every CLI command.

The coding agent does that through related skills provided by, or adapted from, "agent-loop".

The human describes the task, reviews the proposed scope, approves or corrects it, and decides whether anything should become durable project guidance.

The agent operates the loop.

The human governs the decisions that should not be delegated.

The CLI is not the user interface

When people see a CLI project, they naturally assume the workflow looks like this:

vendor/bin/agent-loop workflow plan PROJECT-123 ...
vendor/bin/agent-loop workflow approve PROJECT-123 --by lars
vendor/bin/agent-loop verify
vendor/bin/agent-loop workflow close PROJECT-123 --status done

That is what happens underneath.

It is not how I use it day to day.

I do not manually type an approval command every time a coding agent proposes a plan.

I say:

Yep, approved.

The coding agent recognizes that explicit approval and records it through the workflow.

A normal interaction looks more like this:

Developer:
Fix PROJECT-123.

Invalid order state transitions must be rejected.
Stay inside the order-state validation and its tests.
Run PHPStan and the focused tests.
Show me the plan before changing code.

Coding agent:
I propose the following work brief:

Goal:
Reject invalid order state transitions.

Scope:
Order state validation and focused tests.

Non-goals:
Do not redesign the order aggregate.

Validation:

composer phpstan
composer test

Approve this scope?

Developer:
Yep, approved.

Coding agent:

records the approved revision;
compiles the relevant context;
implements the change;
runs the declared validation;
records the evidence;
reviews blind spots;
reports the result and remaining risks.

That is the actual interface.

The developer talks to the coding agent.

The coding agent operates the workflow.

The CLI provides deterministic state transitions and inspectable evidence behind the interaction.

Otherwise, we would have built a sophisticated automation system whose main achievement was teaching developers to copy longer shell commands.

Start with approved scope

A coding agent should not begin by reading a ticket and creatively filling in everything the ticket forgot to mention.

It should begin by producing an explicit work brief containing:

the goal;
permitted scope;
non-goals;
affected areas;
required validation;
unresolved assumptions;
required human approval.

The human can then answer naturally:

Approved.

Or:

No. Do not change the repository layer.
Keep the scope inside the service and its tests.

Or:

Approved, but the public API must remain unchanged.

The agent records the concrete approved revision internally.

When the plan changes materially, the old revision is no longer sufficient.

The agent must present the updated plan and request approval again.

An approval should apply to a concrete work brief, not permanently to a task ID whose meaning can silently change.

That may sound slightly bureaucratic until an agent performs a technically impressive refactoring nobody requested.

Skills operate the loop

"agent-loop" ships focused operational skills for coding agents working in consuming repositories:

agent-loop-task-start
agent-loop-l2-context
agent-loop-task-progress
agent-loop-review-close
agent-loop-learning-boundary

There is also a broader "agent-loop-workflow" skill that describes the complete workflow and command vocabulary.

The smaller skills are intended for actual coding-agent sessions.

A coding agent loads the skill matching its current stage instead of pulling one giant workflow document into every task.

Their responsibilities are deliberately separated.

agent-loop-task-start
-> inspect the task
-> create a candidate work brief
-> compile initial recall
-> present the scope
-> request human approval
-> record the approved revision

agent-loop-l2-context
-> select relevant project guidance
-> provide bounded context artifacts
-> distinguish supplied context from executed work

agent-loop-task-progress
-> record decisions
-> record checkpoints
-> track scope changes
-> record validation evidence
-> bind evidence to the current plan revision

agent-loop-review-close
-> review blind spots
-> verify the workflow state
-> report remaining risks
-> close only when the required gates pass

agent-loop-learning-boundary
-> capture reusable findings
-> prepare learning proposals
-> prevent automatic promotion into durable guidance

Host repositories can synchronize these skills into their coding-agent environment and adapt them to project-specific conventions.

The result is not a magical agent that understands governance by intuition.

It is an agent with explicit operating instructions and a workflow that leaves evidence behind.

Load less context, not more

The coding agent usually needs two different kinds of context:

project guidance;
code structure.

"agent-recall-compiler" selects task-specific guidance.

"agent-map" provides compact information about the relevant code.

These are separate because they answer separate questions.

Recall:

Which rules apply?
Which previous decisions matter?
What must be validated?
Which constraints conflict?

Map:

Where is this class defined?
Which methods and dependencies are relevant?
Which tests cover this area?
What is the smallest useful code neighbourhood?

The coding agent can use the related skills to invoke these tools itself.

The developer should not need to compile recall output manually, inspect a symbol index, copy selected Markdown into a prompt, and then tell the agent to continue.

The agent should:

build or refresh the relevant map;
compile task-specific recall;
inspect the bounded output;
load only the necessary source ranges;
report missing or conflicting evidence.

The goal is not to compress the complete repository into the prompt.

The goal is to avoid loading most of it.

Dumping a full AST or several months of transcripts into the context window is not understanding.

It is bulk data transport with unusually confident autocomplete.

Keep working memory temporary

During implementation, the agent may need to track:

assumptions;
claimed files;
checkpoints;
open questions;
intermediate decisions;
validation results;
blocked states;
scope changes.

That belongs in a task session.

It should be inspectable, closable, and removable.

Temporary observations should not silently become permanent project knowledge.

A workaround that was useful for one task may become actively misleading after the code changes.

A useful system therefore needs at least three levels:

session state temporary working information
finding evidence requiring review
guidance approved durable knowledge

Collapsing those levels into one memory file removes the provenance that makes information trustworthy.

A note from a debugging session is not automatically a project rule.

A finding is not automatically guidance.

And a selected piece of context is not automatically something the agent actually used.

Verification is part of the loop

An agent saying “done” is not evidence.

The work brief already contains the expected validation commands.

The coding agent runs those commands and records the real results against the approved plan revision.

For example:

Approved scope:
Order state validation and its focused tests

Declared validation:
composer phpstan
composer test

Observed changes:
src/Order/OrderService.php
tests/Order/OrderServiceTest.php

Validation evidence:
composer phpstan -> passed
composer test -> passed

Unexpected paths:
none

The exact commands depend on the repository.

They may include:

composer phpstan
composer test
composer cs

The important rule is:

«Validation must be declared before implementation, not invented afterwards to match whatever changed.»

A passing test suite also does not prove that the agent stayed inside scope.

Tests can pass after an unnecessary architectural rewrite just as happily as after a focused bug fix.

That is why code validation and workflow verification are related but separate concerns.

The workflow must also verify:

whether the current plan was approved;
whether the implementation remained inside scope;
whether validation evidence belongs to the current revision;
whether required review steps were completed;
whether unresolved risk was recorded;
whether the task is actually ready to close.

A polished summary is not a substitute for evidence.

Coding agents are already very good at producing polished summaries.

Selected guidance is not necessarily useful guidance

Recall may select a guidance item for a task.

Selection alone proves nothing.

The guidance may turn out to be:

HELPFUL
IRRELEVANT
HARMFUL
NOT_USED
UNKNOWN

"NOT_USED" is particularly important.

A guidance item may have been selected for an investigation but never actually consulted during implementation.

Without recording that distinction, selection statistics quietly become usage statistics.

The metrics then begin describing a workflow that never happened.

The difference is simple:

selection = the system supplied it
usage = the agent consulted it
outcome = whether it helped

The coding agent can record these outcomes during review.

The developer does not need to maintain a spreadsheet documenting which Markdown fragment appeared in which generated prompt.

Recording selection, usage, and outcome separately gives us evidence for improving recall.

Otherwise, we merely count how often a file was copied somewhere.

Learning still requires a human

After the task, the coding agent may record findings.

A finding is evidence.

It is not automatically a new rule.

The "agent-loop-learning-boundary" skill helps the agent determine whether anything from the task deserves to be presented as reusable knowledge.

A finding may lead to a proposal such as:

ADD
REPLACE
DELETE
REJECT
NO_DURABLE_LEARNING

The agent may:

collect evidence;
identify repeated patterns;
find conflicting guidance;
prepare a proposal;
recommend an outcome.

It must not silently approve its own proposal as durable project knowledge.

A human reviews the proposal before durable guidance changes.

Most tasks should probably end with:

NO_DURABLE_LEARNING

Fixing one bug does not necessarily reveal a reusable project rule.

Sometimes the correct conclusion is simply that the bug was fixed.

That conclusion has its own terminal state:

ACKNOWLEDGED

It is neither approved as a guidance change nor rejected as incorrect.

It records that the result was reviewed and no durable change was needed.

This may look like excessive precision for one status name.

It is not.

When lifecycle states use the wrong verbs, audit trails gradually stop saying what actually happened.

Humans approve decisions, not shell commands

The intended responsibility boundary is:

Coding agent:

inspect the task;
propose scope;
operate agent-loop;
compile relevant context;
edit the code;
run validation;
record evidence;
review blind spots;
report risks;
prepare findings and learning proposals.

Human:

describe the task;
approve or correct the proposed scope;
decide whether expanded scope is acceptable;
review the resulting change;
accept or reject remaining risk;
decide whether proposed knowledge should become durable guidance.

The human communicates those decisions in normal language.

For example:

Yep, approved.

Approved, but do not touch the public API.

No, this is too broad. Keep the existing abstraction.

That additional database migration is outside the approved scope.

The remaining risk is acceptable.

That finding is task-specific. Do not promote it.

Looks good. Close it.

The coding agent converts those decisions into explicit workflow state.

Natural-language confirmation does not bypass the gates.

It triggers the agent to operate them.

Requiring the human to type the corresponding CLI command would not improve governance.

It would merely expose internal plumbing that the coding agent is already capable of operating.

What "agent-loop" actually does

"voku/agent-loop" is a PHP 8.3 CLI that coordinates several focused packages:

agent-kanban work and task state
agent-session temporary working memory
agent-recall-compiler selective project guidance
agent-map compact code intelligence
agent-learning governed durable learning
agent-loop orchestration

The CLI provides deterministic operations and inspectable artifacts.

The accompanying skills teach coding agents when and how to use those operations.

Together, they provide:

skills agent-facing workflow behaviour
CLI deterministic workflow operations
artifacts inspectable state and evidence
humans approval and governance

"agent-loop" does not replace maintainers, code review, static analysis, tests, or domain knowledge.

It gives those existing engineering practices an explicit workflow around coding agents.

Getting started

There are two separate parts:

one-time repository setup
-> install and synchronize the workflow

daily task operation
-> talk to the coding agent

Install the package

Install "agent-loop" in an existing Composer project:

composer require --dev voku/agent-loop

Scaffold the local workflow

Create the minimal local workflow structure:

vendor/bin/agent-loop init scaffold

To inspect what would be created without writing anything:

vendor/bin/agent-loop init scaffold --dry-run

The scaffold creates the initial local workflow inputs when they do not already exist:

.agent-loop/init.json
todo/board.md
todo/cards/DEMO-1.md
tasks/DEMO-1.md
session_plan/
infra/doc/agent-learning/findings/

Existing files are preserved.

"DEMO-1" is a clearly marked example task, not a special workflow mode.

You can inspect it with:

vendor/bin/agent-loop board card show DEMO-1

Synchronize the coding-agent skills

Preview the skill synchronization for Codex:

vendor/bin/agent-loop init sync-skills \
--agent=codex \
--dry-run

After reviewing the planned changes:

vendor/bin/agent-loop init sync-skills --agent=codex

These are setup and maintenance commands.

They are not the normal per-task interface.

The synchronized skills teach the coding agent how to operate the workflow in the consuming repository.

Use the workflow through normal conversation

Once the skills are available, start with an ordinary task request:

Take PROJECT-123.

Reject invalid order state transitions.
Stay inside the service and its focused tests.
Run PHPStan and the tests.
Show me the proposed scope before changing code.

The coding agent inspects the task and presents a candidate work brief:

Goal:
Reject invalid order state transitions.

Scope:
Order state validation and focused tests.

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

Validation:

composer phpstan
composer test

Approve this plan?

You answer normally:

Yep, approved.

The agent then operates the workflow:

record approved revision
-> compile bounded context
-> inspect relevant code
-> implement
-> validate
-> record evidence
-> review blind spots
-> make a learning decision
-> verify
-> report

You can interrupt or redirect it in the same way:

Stop. That migration is outside the approved scope.

The agent must then revise the work brief and request approval for the expanded plan before continuing.

At the end, the agent reports:

what changed;
which validation commands ran;
whether they passed;
whether the approved scope was respected;
which risks remain;
whether any reusable learning was found.

You can respond:

Looks good. Close it.

Or:

The code is fine, but that proposed learning is too broad.
Close the task without promoting it.

The agent records and verifies those decisions through "agent-loop".

You do not manually translate them into CLI commands.

What happens under the hood

Internally, the coding-agent skills may execute operations for:

planning;
approval;
context compilation;
task progress;
validation evidence;
checkpoints;
blind-spot review;
learning decisions;
verification;
closure.

That internal command sequence remains valuable because it provides:

deterministic state transitions;
inspectable artifacts;
revision-bound approval;
validation evidence;
explicit close gates;
auditable learning decisions.

But those commands belong behind the agent-facing skill.

They are similar to database queries behind an application form.

Essential to the implementation.

Not something the user should have to execute manually.

The developer should not need to memorize the workflow commands.

The skill should.

The actual lesson

Coding agents do not need to remember everything.

They need:

agent-operated workflow skills;
explicit scope;
revisioned human approval;
selective context;
temporary working memory;
declared validation;
recorded execution evidence;
human-reviewed learning;
intentional forgetting.

More memory hides bad context management.

A governed loop exposes it.

The purpose is not to make developers manually operate a more elaborate CLI.

The purpose is to give coding agents a repeatable process they can operate themselves, while preserving human control over scope, risk, and durable project knowledge.

The agent does the workflow work.

The human remains responsible for the decisions that matter.

And once the workflow can reject stale approvals, irrelevant guidance, unsupported claims, and accidental lessons, the agent does not need to behave as though it remembers the entire repository.

It only needs enough verified context to complete one controlled task.

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!

PHP: Why I Use Static Analysis

Lars Moelleken — Mon, 26 Jan 2026 05:14:07 +0000

Introduction: Errors Belong to Developers, Not Users

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

Let’s start with something simple and uncomfortable:

If an error happens at runtime, a user sees it.

I don’t care how good your monitoring is, how fast your rollback pipeline runs, or how often you say “it shouldn’t happen”. Runtime errors are already too late. They are failures that escaped development and reached production.

That’s the entire motivation for static analysis.

Not theory. Not fashion. Damage control.

PHP enforces reality.

Static analysis enforces possibility.

Two different layers. Two different failure modes.

And if we can use both, the real question is: why wouldn’t we?

PHP Enforces Reality. Static Analysis Enforces Possibility.

PHP is excellent at telling you when something actually breaks:

calling a method that doesn’t exist
passing a string where an int is required
accessing a property on null

That’s runtime reality.

But PHP is deliberately permissive before that point. It allows code to exist even if it can only fail under certain conditions, in certain branches, or after a refactor.

That’s where static analysis comes in.

Tools like PHPStan don’t compete with PHP. They operate earlier:

when code is written
when it’s refactored
when it’s reviewed
when it’s understood by someone new

PHP tells you what happened.

Static analysis tells you what should never have been possible.

Different jobs. Same goal.

High PHPStan Levels Don’t Just Find Bugs — They Shape Architecture

This is where many people misunderstand strict static analysis.

A high PHPStan level is not about “more errors”.

It’s an architectural pressure system.

It pushes you to:

stop passing anonymous arrays around
stop encoding meaning in strings
stop hiding invariants in comments
introduce value objects, enums, interfaces
define clear boundaries and contracts

And yes, there’s a very pleasant side effect:

👉 IDE autocompletion becomes frighteningly good

Because once types are precise, the IDE actually understands your system.

Not guesses. Not mixed. Not “trust me”.

That’s not cosmetic DX. That’s speed and confidence.

“Let PHP Enforce Contracts” — Good. Now Add the Missing Layer.

“Let PHP enforce contracts.”

Perfect. We should.

But nothing stops you from:

enforcing contracts at runtime and
enforcing them at design time

In fact, PHPStan often nudges you toward better PHP:

stricter parameter types
explicit return types
real interfaces instead of conventions
enums instead of magic strings

Using static analysis doesn’t weaken PHP’s guarantees.

It narrows the space in which PHP ever has to complain.

DX Matters: Instant Feedback Beats Any Test Suite

One of the most underrated benefits is developer experience.

If a function declares:

/**
 * @param int<1, 32> $limit
 */
function paginate(int $limit): void {}

And I pass 64, I want that error:

immediately
in my IDE
without running tests
without pushing code
without involving CI

That feedback loop is priceless.

Static analysis is the only tool that gives you semantic errors at typing speed.

Security: `literal-string` Is a Real Guardrail

This is not theoretical.

/**
 * @param literal-string $sql
 */
function runRaw(string $sql): void {}

This single constraint:

blocks user input
blocks “temporary” hacks
blocks accidental string concatenation
blocks whole classes of SQL injection mistakes

Does it solve all security? Of course not.

Does it eliminate dumb, expensive errors early? Absolutely.

Documentation That Cannot Lie

Traditional documentation rots because nothing enforces it.

Static PHPDoc does.

When you write:

/**
 * @return Generator<int, User>
 */
function users(): Generator {}

You’ve documented:

key type
value type
iteration semantics

And if reality diverges? The build fails.

As a bonus:

the IDE knows $key is int
the IDE knows $user is User
refactors are safe
onboarding is faster

This is documentation with teeth.

Logic Bugs Still Exist 😊 — And That’s Fine

Let’s get this out of the way:

Static analysis does not prevent logic bugs.

Nothing does — except thinking.

But static analysis removes:

type bugs
shape bugs
nullability bugs
refactor bugs
“this can never happen” bugs

Those are not interesting problems.

They’re noise.

I prefer to spend my brainpower on logic and design, not on mistakes a machine can detect instantly.

The Practical Rule Set That Actually Works

This is how static analysis succeeds in real PHP codebases:

keep arrays and strings at the boundaries (HTTP, JSON, DB)
validate once
convert once
after that: objects, enums, value objects
baseline legacy code
tighten rules only where you touch code
never weaken types just to silence the tool

No rewrites. No greenfield fantasies.

Just steady entropy reduction.

Conclusion: Two Layers Are Better Than One

PHP enforces reality.

Static analysis enforces possibility.

Runtime errors mean errors for users.

Static errors mean errors for developers.

High PHPStan levels shape architecture for the better and massively improve IDE feedback.

Nothing prevents you from using strong PHP types and static analysis — in fact, they reinforce each other.

Logic bugs still require thinking 😊

But type bugs are optional.

And I prefer optional bugs to be… not present.

Summary

Runtime errors are user-facing failures
Static analysis shifts errors to development time
High PHPStan levels improve architecture and DX
Security and documentation benefit immediately
PHP and PHPStan are complementary, not competing
Logic bugs remain — but the boring ones disappear

What’s Next?

Using PHPStan as an architectural guardrail
Static analysis as a safety net for LLM-generated code (with a fast feedback loop)
Killing mixed once and for all

Happy Coding.