vibe-code

Software Architecture Vibe Coding

Purpose

Help Claude code quickly without creating architecture drift. Use the smallest professional workflow that fits the task. Do not add ceremony for trivial edits, and do not generate broad rewrites when a focused change solves the request.

Core rule:

Fast coding is allowed. Architecture drift is not.

When to Use

Use this skill for feature work, bug fixes, refactors, plugin work, APIs, exporters, simulations, BIM/XR/robotics tools, or cleanup of AI-generated code.

Do not force the full workflow for a typo, one-line setting change, copy edit, or disposable script.

Task Classification

Classify the work before coding.

Tiny change

Examples: text edit, one constant, one import, one obvious bug line. Apply directly after checking the immediate context. Do not touch unrelated code.

Local change

Examples: one function, component, class, command, script, or test area. Inspect nearby code, match existing style, and avoid new abstractions unless they remove real coupling or duplication.

Architectural change

Examples: new feature, new module, new dependency, new file format, database/API boundary, exporter, SDK integration, multi-file refactor, or domain rule change. Do a short design pass before implementation and keep the slice small.

When uncertain, treat the task as local or architectural until repository inspection proves it is tiny.

Core Engineering Rules

1. Inspect first. Read the relevant files, entry points, tests, and configuration before changing non-trivial code.

2. Control dependency direction. UI, CLI, API, commands, jobs, and framework glue should depend on application use cases. Application code may depend on domain models and ports. Infrastructure adapters should depend inward, not the other way around.

3. Keep policy separate from detail. Domain decisions and business rules should not be hidden in UI handlers, SDK callbacks, database code, HTTP clients, file exporters, or vendor-specific APIs.

4. Treat external tools as details. Revit, Unity, ROS, IFC, USD, glTF, databases, file systems, web frameworks, cloud SDKs, and LLM APIs should sit behind boundaries when their behavior affects domain logic or testing.

5. Hide changeable decisions. Isolate file formats, protocols, coordinate systems, unit conversion, thresholds, caching, and vendor APIs when they are likely to change. Do not create interfaces only for decoration.

6. Design around stable concepts. Prefer names and modules based on domain meaning, responsibilities, and data flow over button clicks, screens, or implementation steps.

7. Keep changes surgical. Touch only what the request requires. Preserve existing style. Do not refactor adjacent code unless the requested change cannot be made safely without it.

8. Implement a vertical slice. For larger work, connect the smallest useful path through data model, use case, adapter/UI, and tests. Avoid half-built frameworks.

9. Make failure behavior explicit. Handle realistic errors at boundaries. Do not hide failures with broad catch-all logic or silent fallbacks.

10. Leave evidence. Add or update tests where behavior changes. Run the most relevant verification command available in the repo.

Workflow

For non-trivial work:

1. Identify the goal, affected files, current architecture, and likely boundary.
2. State the classification: tiny, local, or architectural.
3. For architectural changes, name the intended dependency direction and the smallest safe slice.
4. Implement only that slice.
5. Remove unused code introduced by the change.
6. Run focused tests or checks.
7. Report what changed, what was verified, and any remaining risk.

Ask the user only when a decision materially changes behavior, public API, data shape, migration risk, or user-visible workflow and cannot be resolved from the repo.

Testing Expectations

Match test effort to risk:

• Tiny change: inspect result or run the narrowest cheap check.
• Local change: add or update focused tests if behavior changes.
• Architectural change: test the domain/use-case boundary and at least one adapter or integration path when practical.

If tests cannot run because dependencies, tools, permissions, or environment are missing, say exactly what was not run and why.

Final Response

Keep the final answer short and concrete:

• changed behavior or files
• verification performed
• remaining risks or skipped checks

Do not over-explain the architecture unless the user asks.