Engineering
Engineering
Engineering notes from AmanERP on AI-native software, verification, audit trails, and operating with rigor in public.
OPEN SOURCE LICENSING
The AGPL Trap That Forced an Identity Provider Migration
Why AGPL license risk forced a six-week identity-provider migration: the Go static-linking trap, the two-axis license matrix, and the rule that keeps product code safe.
AI ENGINEERING
Prompting Is a Control Plane, Not a Vibe
Treat prompts as an engineering control plane: scope the task, point to sources, name checks, state constraints, and make evidence mandatory.
SPEC DISCIPLINE
Spec Before Speed: The Cheapest Place to Catch Scope
Before an AI agent writes code, make the ticket engineering-ready: objective, boundaries, acceptance criteria, definition of done, and deliverables.
AGENT ORCHESTRATION
Parallel Agents Need Air-Traffic Control
Parallel AI engineering needs sequencing, file ownership, a concurrency ceiling, and supervisor discipline before it needs more agents.
VERIFICATION
Evidence Beats Assertion in AI Engineering
AI agents should report commands, outputs, exit codes, and screenshots, not confidence. Verification is a contract, not a mood.
CODE REVIEW
The Adversarial Review Loop That Keeps AI Useful
A useful AI review loop separates planning, adversarial critique, implementation, branch review, and only the high-confidence fixes.
DEBUGGING
Debugging Starts After the First Counterexample
Disciplined AI debugging starts with evidence, ranked hypotheses, a reproduction, and a root-cause fix rather than patching the symptom.
SOFTWARE TESTING
Tests Must Be Able to Fail for the Right Reason
Useful AI-generated tests assert behavior, cover acceptance criteria, avoid fake mocks, and prove they can fail for the right reason.
CONTEXT HYGIENE
Context Is a Budget, Not a Backpack
Treat context as a finite operating budget: offload broad investigation, write handoffs, preserve decisions, and restart before drift becomes rework.
PR HYGIENE
Clean PRs Are an Engineering Interface
AI-written code still needs human-reviewable commits and PRs: exact staged scope, clear intent, risk, rollback, and distinct gate status.
ENTERPRISE UX
Premium UX Review Is Not Taste, It Is Operations
Premium UX critique should inspect workflow, hierarchy, state coverage, interaction, copy, and information availability, not generic styling opinions.
RELIABILITY ENGINEERING
Your Server Said 'Healthy.' The Database Had Zero Tables.
A database connection proves TCP and auth, not that the schema exists. The silent empty-database failure, and the one health-check that actually catches it.
SOFTWARE TESTING
181 Tests Passed. Zero Features Worked.
181 tests passed while the app had zero tables, dead metrics, and broken auth. What mock-only tests prove, what they miss, and the layer that closes the gap.
AI-NATIVE VERIFICATION
git commit -- file.go Doesn't Limit Scope. It Does the Opposite.
git commit pathspec re-stages the file's whole working tree. With parallel AI agents sharing one git index, that means ghost commits. Here's the fix.
AI-NATIVE VERIFICATION
100% Mutation Efficacy, Zero Mutants Killed: A Gate That Asserts Nothing
A mutation-testing gate reported 100% efficacy with 0 mutants killed — all 603 were timeouts. A gate that asserts nothing scores perfectly. Why filed ≠ solved.
ENGINEERING DISCIPLINE
Schema-Aware Gates: Validate, Don't Coerce
Schema-aware gates should validate and fail closed. Defaulting missing fields to zero turns a correctness gate into false evidence.
ARCHITECTURE DECISIONS
RFC Before ADR: The 'Maybe' Layer That Saves Bad Decisions
An RFC layer between idea and ADR records rejected options, open questions, and constraint tradeoffs before decisions become permanent.
Articles for owners, operations leads and their accountants: Read the blog