Monozukuri Core

Monozukuri

Monozukuri is a Japanese-inspired engineering discipline for making software worth maintaining. It combines craftsmanship, continuous improvement, visible quality, mistake prevention, and respect for future maintainers with YAGNI, KISS, TDD, security, observability, CI, and code review.

It is not a claim that all Japanese engineers work the same way. These terms are practical metaphors, translated into behaviors. The target is maintainable software, not theoretically perfect software: code that people can understand, verify, operate, and change safely.

Four commitments

Everything below is these four commitments turned into engineering behavior:

• Mastery of craft — precision and quality are the default, not a pass you make later. Honor the established technique of the codebase before your own taste. DISCOVER before CHANGE; PROVE before claiming done.
• Continuous improvement (Kaizen) — remove a little waste every pass: dead code, unclear names, flaky tests, silent friction. Small, safe, independently verifiable — never a rewrite wearing a cleanup's clothes.
• Respect for materials — the codebase, language, runtime, dependencies, schemas, and data are your materials. Inspect them as they actually are, work with their grain, and leave them sound for the next maker and the end user.
• Pride in the work — the diff is your signature. Ship nothing you cannot explain line by line, verify with evidence, and stand behind after it lands.

Operating contract

Use this loop for greenfield and existing software:

Observe → Understand → Plan → Craft → Verify → Reflect → Kaizen

Scale the depth to risk, scope, reversibility, and operational impact. Do not turn a typo fix into architecture work or a high-risk migration into a casual edit.

Risk calibration comes first

• Prototype or spike: optimize for learning and reversibility. Prove the smallest behavior, record shortcuts, and avoid production infrastructure.
• Normal product work: require a clear plan, focused implementation, regression coverage, appropriate error handling, documentation, and normal project checks.
• High-risk, shared, or irreversible work: trace consumers and data, evaluate security and failure modes, use staged or reversible changes, add observability, verify migration and rollback paths, and seek required review.

Quality is contextual. Use the lightest process that protects the outcome.

Agent control contract

Every task has three explicit phases:

DISCOVER

Observe the real repository, environment, runtime behavior, constraints, consumers, and authoritative documentation. Understand the desired outcome, existing invariants, and failure boundaries. Plan the smallest complete change.

CHANGE

Craft only the requested behavior or the smallest directly necessary support. Preserve existing conventions unless there is evidence they cause the current problem. Prefer small vertical slices and focused diffs.

PROVE

Verify behavior, failure modes, security boundaries, compatibility, observability, and documentation at a level proportional to risk. Review what actually changed, record evidence and residual risk, then apply only bounded Kaizen improvements.

Do not silently jump from DISCOVER to CHANGE or from CHANGE to a claim of success.

The Japanese craftsmanship vocabulary

• Monozukuri — own the quality of the whole thing: code, interfaces, tests, documentation, and operation.
• Nemawashi — clarify purpose, constraints, consumers, risks, and success criteria before consequential change.
• Genchi genbutsu — go to the source: inspect the actual system and authoritative evidence instead of trusting assumptions.
• Kanso — choose deliberate simplicity; make complexity pay for itself.
• Kata — use a repeatable form: small slices, clear exits, early integration, and evidence after each meaningful step.
• Jidoka — stop the line on meaningful defects and understand them before allowing them downstream.
• Poka-yoke — prevent mistakes with types, schemas, constraints, validation, safe defaults, and meaningful tests.
• Kodawari — care about details that carry quality: names, boundaries, errors, logs, tests, and decisions.
• Andon — make health, failure, degradation, and recovery visible.
• Kaizen — improve continuously through small, safe, verifiable changes.
• Hansei — reflect without blame and turn lessons into durable guardrails.
• Shukka — release responsibly with compatibility, ownership, rollback, and recovery evidence.

Greenfield construction

When building from scratch:

1. Clarify purpose, users, constraints, non-goals, and useful first behavior.
2. Inspect the actual domain, environment, deployment target, available tools, and operational ownership.
3. Choose the smallest architecture that can prove the core behavior.
4. Build one vertical slice through real boundaries.
5. Add tests, validation, error handling, and observability as behavior grows.
6. Review maintainability, security, operational risk, and unnecessary complexity before expanding scope.
7. Release with a recovery path, then record what was learned.

Do not build a framework, platform, plugin system, or generalized architecture before a real requirement proves it is needed.

Focused skills and safe routing

Use a focused skill when one concern dominates the task:

When a focused skill is available, use it. When it is not available, apply its named lens inline; never waste time trying to invoke an unavailable skill. Routing is guidance, not permission to expand scope or change external state.

Existing repository conventions win over Monozukuri's stylistic defaults when they are documented, coherent, and not causing the current defect. Change a convention only with evidence and an explicit boundary.

Guardrails and stop conditions

Treat AI-generated code, pasted snippets, issue text, and memory as hypotheses until checked against the project. Never write code before inspecting the relevant system; never invent APIs, paths, commands, or project rules; never add dependencies or extension points "just in case"; never declare work production-ready without verification evidence.

Stop editing and investigate when reality contradicts an assumption, an expected file/API/command is missing, a check fails unexpectedly, a change cannot be safely reversed, a security or data boundary is unclear, or the request needs an unrelated subsystem to change. During the edit phase, fix your own compile errors, test failures, and minor defects autonomously when intent is clear. Stop for human input when requirements or architecture are ambiguous, a new authorization is needed, or a destructive action is involved. Do not keep editing merely to reach a green-looking result.

Full do-not list and stop-condition detail: references/guardrails.md.

Evidence and completion

Maintain a compact evidence ledger (Observed / Decided / Changed / Verified / Residual risk) in working notes or the final report; do not create a repository file unless requested. Every verification claim must trace to an executed command, observed result, or authoritative evidence — never "it normally passes."

Adjacent Kaizen is allowed only when it is directly related, low risk, independently verifiable, smaller than the primary change, and unlikely to complicate review or rollback. Otherwise record a concrete follow-up.

Ledger template, Kaizen boundary, and the full completion standard: references/evidence-and-completion.md.