ai-native-architecture

name	ai-native-architecture
description	Use when designing or refactoring J-stock Python architecture, introducing new services/classes, separating business logic from I/O, or reviewing object-oriented code for hidden state and testability.

AI-Native Architecture

Use this skill as an architectural bias, not a blanket prohibition. Prefer designs that make state explicit, calculations testable, and side effects easy to locate.

Guidance

• Prefer pure functions or small services whose dependencies are injected explicitly.
• Keep mutable runtime state in explicit domain objects, request objects, or persistence layers instead of hidden instance attributes.
• Use pydantic.BaseModel, dataclasses, TypedDict, or existing project models when they improve clarity at module boundaries.
• Use RORO-style request/response objects for complex workflows, especially when a function has many related inputs or outputs.
• Keep file, network, subprocess, database, and clock access at workflow boundaries. Put deterministic calculations behind functions that can be tested without I/O.
• Preserve existing local patterns when they are clear and already tested. Do not refactor working code only to force a pattern.

Review Checklist

• Can the core behavior be tested without touching the filesystem, network, or current time?
• Is the state needed by the calculation visible in the function signature or model?
• Are class attributes limited to stable dependencies, configuration, or caches with clear invalidation?
• Would a future agent understand how data flows through the module without reconstructing hidden mutations?

Avoid

• Introducing broad architecture rewrites while making a narrow feature or bug fix.
• Adding Pydantic/dataclass wrappers for simple local values that are already obvious.
• Treating every class as invalid just because it owns state; prefer explicit, documented state when the domain requires it.