Skip to main content
rule CX Codex

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

Install into Claude Code · Manually: put the files in place All methods and platforms ↓
.claude/rules/1-conventions.md
Open on GitHub

What 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.md

The paths frontmatter field limits the files

Step 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

Similar IDE rules

All IDE rules for Testing and QA →

From the same set80

The whole set →
06-agent-generate 06-agent-generate generates agent and subagent scaffolds across the AI coding tools configured in your project from a role prompt. CX Codex +1 ★ 571repo stars 02-challenge 02-challenge is a Claude Code skill that checks completed work against an agreed plan and returns a structured report. Its findings help decide whether to ship, revise, or rework the result. CX Codex +1 ★ 571repo stars 05-spike 05-spike turns one blocking unknown into a bounded spike: frames the question, gathers evidence, writes the outcome. CX Codex +1 ★ 571repo stars 0-contexts 0-contexts enforces one-way imports across bounded contexts and keeps business logic out of the shared kernel in TypeScript projects. CX Codex +1 ★ 571repo stars 05-rule-generate 05-rule-generate takes a coding rule from draft to the rule files of installed AI hosts: create, edit, publish, delete. CX Codex +1 ★ 571repo stars 07-command-generate 07-command-generate generates flat slash commands across the AI assistants enabled in your repository. Useful when you need to scaffold or edit single-step commands without manual path wiring. CX Codex +1 ★ 571repo stars 0-hexagonal The 0-hexagonal rule splits each context into four layers and keeps dependencies pointed inward. Use it when reviewing TypeScript architecture. CX Codex +1 ★ 571repo stars 09-mermaid 09-mermaid turns a written description of an architecture or a flow into a Mermaid diagram, with a plan you approve before anything gets drawn. CX Codex +1 ★ 571repo stars

Project sponsors

Companies that keep this analytics open