AI repository standards
for long-term maintainability
Structured repository conventions designed to keep AI-generated code predictable and maintainable over time.
Server Components First
Always prefer server components unless interactivity is required.
Reduces client-side complexity and avoids unnecessary hydration.
Fetching data inside client components.
Fetch data in server components and pass serialized props.
Duplicated fetching logic across pages.
Used inside: billing workflow, dashboard modules, shared validators
Old dashboard hooks still depend on legacy validation patterns.
Partially migrated.
Feature-Based Structure
Group files by feature instead of file type.
Keeps features self-contained. Prevents AI from creating scattered utilities.
Flat file structure with no domain boundaries.
/features/auth, /features/billing, /features/dashboard
Mixed concerns and duplicated logic across features.
Used inside: billing workflow, dashboard modules
Old dashboard modules still use flat structure.
Partially migrated.
Shared UI Primitives
Avoid duplicated UI patterns. Keep reusable UI in /components/ui.
AI tools generate inconsistent UI without shared primitives.
Inline styles and duplicated button patterns across features.
Button, Input, Dialog reused from /components/ui
Inconsistent UI generated by different AI prompts.
Used inside: all dashboard modules
Analytics module still uses inline styles.
Migration in progress.
Isolated Business Logic
Never mix UI rendering with domain logic.
Keeps AI-generated code testable and refactorable.
API calls and state management inside component files.
Logic in /features/*/actions or /features/*/hooks
Server actions mixed with UI rendering code.
Used inside: billing service, auth module
Dashboard components still contain inline queries.
Pending.
Naming Conventions
Use explicit names. Avoid generic file names.
Generic names cause AI tools to create duplicated utilities.
helpers.ts, utils.ts, common.ts
auth-validator.ts, billing-service.ts, dashboard-query.ts
Duplicated utility files with overlapping logic.
Used inside: all feature modules
Legacy utils/ folder still contains mixed helpers.
Partially migrated.
PR Constraints
Keep PRs under 300 LOC. Avoid mixed concerns.
Large PRs hide AI-generated inconsistencies and duplicated patterns.
500+ line PRs with multiple unrelated changes.
Focused PRs under 300 LOC with clear scope.
Inconsistent architecture hidden in oversized PRs.
Used inside: all workflow repositories
Billing migration PRs still exceed 400 LOC.
Enforcing new limits.
Testing Standards
Test critical flows. Prefer integration tests.
AI-generated code often misses edge cases and error states.
Snapshot-heavy tests that hide regressions.
Behavior-based tests covering loading, error, and empty states.
Tests passing but production flows broken.
Used inside: billing, auth, dashboard
Old test files still use snapshot approach.
Migration in progress.
Performance Standards
Lazy load heavy charts. Avoid client waterfalls.
AI tools don't consider bundle size unless constrained.
All components eagerly loaded on the client.
Server components with streaming and lazy-loaded heavy UI.
Unnecessary client bundles slowing down page loads.
Used inside: dashboard, analytics
Analytics page still eagerly loads charts.
Pending.
AI Output Constraints
Preserve existing architecture. Avoid introducing new folder structures.
AI tools generate alternative patterns unless strictly constrained.
AI creating new folder structures outside feature boundaries.
AI following existing feature-based architecture patterns.
Inconsistent repo structure from unconstrained AI output.
Used inside: all AI-generated code paths
No legacy exceptions — all new code must follow constraints.
Fully active.
Migration Constraints
Old patterns still exist. Prevent AI from adding to legacy code.
AI tools can't distinguish between current and deprecated patterns.
AI adding new features using deprecated hook patterns.
AI following migration guide and using current standards.
Legacy patterns duplicated across new features.
Used inside: billing hooks, dashboard queries
Auth hooks still use deprecated patterns.
Migration planned Q3 2026.
memory.md
architecture.md
migration-notes.md
testing-guidelines.md
pnpm-workspace.yaml
turbo.json
- duplicated auth hooks introduced during billing refactor
2026-05-04
- dashboard migration broke validation consistency
2026-04-28
- old analytics modules bypassed server boundaries
- preserve migration consistency
- maintain repo predictability
- reduce architectural drift
- avoid duplicated business logic