1-conventions — Claude Code rule: what it does, how to install
The 1-conventions rule sets conventions for TypeScript files under src/ and tests/, covering module structure, file names, and test tiers. Use it when adding code or tests to a project.
MIT ★ 571 updated 2026-10-29
.claude/rules/1-conventions.mdWhat 1-conventions does
The rule applies to src/**/*.ts and tests/**/*.ts. It requires named exports, disallows barrel files and re-exports, and calls for relative imports with a .js extension. Type-only imports use import type. Files follow kebab-case.ts; test tiers are marked with .unit.test.ts, .integration.test.ts, or .e2e.test.ts.
Architecture tests have a location requirement: a *.arch.test.ts file must live in tests/architecture/ or it will not run. The tests/ tree mirrors src/. The rule uses pnpm jscpd to fail on copied blocks and recommends extracting shared code when a second caller appears. Filename suffixes matter here: the checks rely on them, so a misnamed file can escape detection.
For Claude Code, add .claude/rules/1-conventions.md to the project. Separate paths are provided for Cursor and GitHub Copilot. The scope is TypeScript files, so files with other extensions are outside these conventions.
What it helps with
- set consistent export and import conventions for TypeScript modules
- name files and symbols according to project conventions
- mark unit, integration, and e2e tests through file suffixes
- catch duplicated code with
pnpm jscpd - place architecture tests where the test setup can run them
Example prompts for the agent
- Add a module under
src/and follow the export and import conventions. - Create a unit test for this module using the required filename suffix.
- Find out why this architecture test is not running.
How to install 1-conventions
Manually: put the files in place
.claude/rules/1-conventions.mdThe paths frontmatter field limits the files
AGENTS.md
Codex reads AGENTS.md: paste the rule text there
Manually: put the files in place
.cursor/rules/1-conventions.mdcFrontmatter: description, globs, alwaysApply
Manually: put the files in place
.github/instructions/1-conventions.instructions.mdThe applyTo field sets which files it applies to
Manually: put the files in place
.devin/rules/1-conventions.mdManually: put the files in place
.clinerules/1-conventions.mdStep by step, with commands for each platform: AGENTS.md vs CLAUDE.md: what they are and which one to use
Questions about 1-conventions
How do I install 1-conventions in Claude Code?
Add the rule as .claude/rules/1-conventions.md in your project.
What does 1-conventions do?
It sets conventions for TypeScript files in src/ and tests/, including module exports, imports, naming, and test placement.
Why might an architecture test not run?
A *.arch.test.ts file outside tests/architecture/ does not run. Check its location.
Source text
1-conventions.md · MIT
---
description: Apply to every source and test file; module shape, naming and test tiers.
paths:
- "src/**/*.ts"
- "tests/**/*.ts"
---
# Conventions
## Modules
- Named exports only; biome's `noDefaultExport` holds it under `src/` and `tests/`.
- No barrel, no re-export: biome's `noBarrelFile`, `noReExportAll`, `noExportedImports`, plus `no-re-export.arch.test.ts` for `export { x } from` (`tests/helpers/ports/` exempt).
- Import from the defining module, relative, `.js` extension.
- `import type` for a type-only import.
## Names
- `kebab-case.ts` files; suffixes `-adapter.ts`, `-use-case.ts`.
- A port file is named for its interface: `file-merger.ts` for `FileMerger`.
- The ratchets read those suffixes; a misnamed file is invisible.
- `camelCase` values, `PascalCase` types, `CONSTANT_CASE` module constants.
- A leading underscore marks a parameter an interface forces.
- Name the intention: `applyFrameworkFile`, not `writeThenHash`.
- `executeInternal` means no concept was found; do not make it.
## Tests
- The extension declares the tier: `*.unit.test.ts`, `*.integration.test.ts`, `*.e2e.test.ts`.
- An `*.arch.test.ts` outside `tests/architecture/` runs nowhere.
- `tests/` mirrors `src/`.
## Duplication
- `pnpm jscpd` fails a copied block.
- Extract at the second caller (`0-shared-modules.md`).
© ai-driven-dev · MIT · ai-driven-dev/framework