Codebase Organization for AI-Assisted Development

ai-toolsorganizationconventions

Conventions for structuring codebases so AI coding assistants can navigate, understand, and generate accurate code with minimal confusion or hallucination.

Целевые файлы

Файл	Формат
.cursorrules	plaintext
CLAUDE.md	markdown

Содержимое

# Codebase Organization for AI-Assisted Development ## File & Directory Naming - Use `kebab-case` for all file and directory names. Avoid camelCase filenames — they cause case-sensitivity issues on Linux. - Name files after their primary export: `user-service.ts` exports `UserService`. One primary export per file. - Group by feature, not by type: prefer `features/auth/` over `services/`, `controllers/`, `models/` silos. - Index files (`index.ts`) are allowed only for re-exporting — never for implementing logic. ## Module Boundaries - Define clear module boundaries with explicit public APIs (index files or barrel exports). - Internal modules use relative imports; cross-module imports use path aliases (`@/features/auth`). - Never import internal implementation files from another module — only import from the module's public API. - Circular dependencies are forbidden. Run `madge --circular` or equivalent as part of CI. ## Colocation - Co-locate tests with source: `user-service.test.ts` next to `user-service.ts`. - Co-locate types with their consumers — only promote to shared types when used across 3+ modules. - Co-locate component styles (CSS Modules, styled-components) with the component file. - Co-locate mock/fixture files in a `__mocks__` or `fixtures/` folder adjacent to the module. ## Naming Conventions for AI Clarity - Use consistent noun/verb patterns: repositories are nouns (`UserRepository`), services are nouns (`AuthService`), utilities are noun+descriptive (`DateFormatter`, `StringUtils`). - Prefix boolean variables and functions: `isLoading`, `hasPermission`, `canEdit`, `shouldRetry`. - Suffix types clearly: `*Service`, `*Repository`, `*Controller`, `*Dto`, `*Entity`, `*Schema`, `*Config`. - Avoid generic names: `utils.ts`, `helpers.ts`, `misc.ts` — use specific names like `format-date.ts`, `validate-email.ts`. ## Context Anchors - Add a one-line comment at the top of each complex file stating its role: `// Domain service for user authentication and session management`. - Document non-obvious architectural decisions with `// ARCHITECTURE:` comments explaining the why. - Mark integration points: `// EXTERNAL: calls Stripe API` or `// DB: writes to orders table`. ## Dependency Management - Pin exact major versions in `package.json` for AI tools to reference accurate APIs. - Keep a `docs/ADRs/` directory with Architecture Decision Records for major choices. - Document third-party library wrappers — explain why you wrapped and what the wrapper adds. ## Configuration - Centralize all configuration in a single `config/` or `src/config/` module. Never scatter config across files. - Use typed config objects — `Config` interface with all keys explicit. No string-key access. - Separate environment-specific config from feature config. Document every environment variable. ## Anti-Patterns - Do not create `god modules` — files exceeding 300 lines likely need splitting. - Do not use magic numbers or magic strings inline — export named constants. - Do not leave dead code (commented-out blocks, unused exports) — delete it; git history preserves it. - Do not use ambiguous abbreviations: `mgr`, `ctrl`, `svc` — spell them out. - Do not mix concerns in a single file: HTTP handling + business logic + DB access in one file is a red flag. ## Documentation Targets - Every public function and class must have a JSDoc/docstring with params, return type, and one example. - Every module's `index.ts` or `README.md` must describe the module's purpose in 2 sentences.

CLI

npx mindaxis apply codebase-organization-rules --target cursor --scope project

Используется в паках

AI Prompting Toolkit

Master Claude, Codex, and LLM prompt engineering

Открыть пак →

Cursor Pro Workflow

Supercharge Cursor IDE with AI-assisted coding patterns

Открыть пак →

← Правила

Codebase Organization for AI-Assisted Development

ai-toolsorganizationconventions

Conventions for structuring codebases so AI coding assistants can navigate, understand, and generate accurate code with minimal confusion or hallucination.

Целевые файлы

Файл	Формат
.cursorrules	plaintext
CLAUDE.md	markdown

Содержимое

CLI

npx mindaxis apply codebase-organization-rules --target cursor --scope project

Используется в паках

AI Prompting Toolkit

Master Claude, Codex, and LLM prompt engineering

Открыть пак →

Cursor Pro Workflow

Supercharge Cursor IDE with AI-assisted coding patterns

Открыть пак →