Merge pull request #9 from boostcampwm-snu-2026-1/docs/8-code-conventions

docs: add code conventions

Author: britle20

AGENTS.md

@@ -47,6 +47,7 @@ If these scripts do not exist yet, future scaffold work must add them. CI uses `
 - Keep project data serializable.
 - Store musical time in ticks, not seconds.
 - Use TypeScript types for project data, audio engine APIs, and feature boundaries.
+- Follow `docs/code-conventions.md` for naming, file organization, TypeScript, React, CSS Modules, design tokens, domain naming, tests, and comments.
 - Prefer pure utilities for tick math, model transformations, and scheduler calculations.
 - Do not introduce new production dependencies without a clear reason.
 - Do not rewrite large files unless required.

PLANS.md

@@ -29,7 +29,7 @@ M1 should include:
 
 Use this section as the current execution order for agent work. Feature document numbering describes the planned product sequence, but actual issue order may change as dependencies, review feedback, or implementation risks become clearer.
 
-1. #6 Project Scaffold -> `docs/features/01-project-scaffold.md` (PR #7 in review)
+1. #8 Document Code Conventions -> `docs/code-conventions.md` (PR #9 in review)
 2. #4 AudioContext and Sample Playback -> `docs/features/02-audio-context-and-sample-playback.md`
 3. #5 Lookahead Scheduler -> `docs/features/03-lookahead-scheduler.md`
 4. #3 Drum Step Sequencer -> `docs/features/04-drum-step-sequencer.md`

README.md

@@ -46,6 +46,7 @@ The scaffold provides these scripts. Feature-specific behavior will be added in
 - [Audio engine](docs/audio-engine.md)
 - [UI and design](docs/ui-design.md)
 - [Testing strategy](docs/testing.md)
+- [Code conventions](docs/code-conventions.md)
 - [Project plans](PLANS.md)
 - [Agent instructions](AGENTS.md)
 

docs/code-conventions.md

@@ -0,0 +1,87 @@
+# Code Conventions
+
+## Purpose
+
+Use these conventions to keep agent-authored code consistent across features. Prefer existing local patterns when they are more specific than this document.
+
+## Files and Directories
+
+- React component files use `PascalCase.tsx`: `TransportBar.tsx`, `PianoRoll.tsx`.
+- Component CSS Modules use the same base name: `TransportBar.module.css`.
+- Feature folders use `kebab-case`: `drum-step-sequencer`, `piano-roll`.
+- General TypeScript utility files use `kebab-case.ts`: `tick-time.ts`, `sample-loader.ts`.
+- Barrel files may use `index.ts` only when they simplify imports without hiding ownership.
+- Test files use `*.test.ts` or `*.test.tsx` next to the code they cover unless a feature establishes a clearer local pattern.
+
+## TypeScript Naming
+
+- Types, interfaces, classes, enums, and React components use `PascalCase`.
+- Functions, variables, object properties, and module-level helpers use `camelCase`.
+- True constants use `UPPER_SNAKE_CASE`: `DEFAULT_PPQ`, `BAR_TICKS`, `STEP_TICKS`.
+- Generic type parameters should be short and meaningful: `T`, `TEvent`, `TClip`.
+- Avoid abbreviations unless they are common in the domain, such as `MIDI`, `PPQ`, `BPM`, or `ID`.
+
+## React Components
+
+- Component names should match product nouns: `TransportBar`, `ClipEditor`, `DrumStepSequencer`.
+- Event handlers use `handleX`: `handlePlayClick`, `handleStepToggle`.
+- Custom hooks use `useX`: `useTransportState`.
+- Components should not own exact audio timing or scheduling logic.
+- Keep feature-specific UI under `src/features/` unless it is clearly reusable.
+- Keep shared presentational components under `src/components/`.
+
+## Domain Naming
+
+- Tick values should use `Tick` or a `Ticks` suffix when they represent a duration or length:
+  - `startTick`
+  - `durationTicks`
+  - `lengthTicks`
+- Seconds should be explicit:
+  - `durationSeconds`
+  - `lookaheadSeconds`
+  - `scheduleAheadSeconds`
+- Web Audio clock values should make audio-time semantics clear:
+  - `audioStartTime`
+  - `scheduledAudioTime`
+- IDs use `Id` suffix in property names:
+  - `clipId`
+  - `trackId`
+  - `sampleId`
+- Booleans should start with `is`, `has`, `can`, or `should`:
+  - `isPlaying`
+  - `hasSelection`
+  - `canResizeNote`
+  - `shouldLoop`
+
+## CSS Modules
+
+- CSS Module class names use `camelCase`: `root`, `transportBar`, `stepButton`, `activeStep`.
+- Prefer product or component part names over visual-only names.
+- Keep static appearance in CSS Modules.
+- Runtime editor geometry may use inline styles when values are derived from ticks, pitch, or grid dimensions.
+- Do not put component-specific styles in global CSS.
+
+## Design Tokens
+
+- Define primitive tokens first: raw palette, spacing, typography, radius, and timing values.
+- Define semantic tokens from primitive tokens.
+- Component CSS Modules should use semantic tokens, not primitive tokens.
+- Primitive token example: `--color-neutral-900`, `--space-4`, `--radius-2`.
+- Semantic token example: `--color-app-background`, `--space-control-gap`, `--radius-control`.
+- Document exceptions when component code must reference a primitive token directly.
+
+## Tests
+
+- Test names should describe behavior, not implementation.
+- Prefer examples such as:
+  - `converts ticks to seconds at 120 bpm`
+  - `does not schedule duplicate events at the loop end`
+- Unit-test pure utilities, tick/time conversion, data model transformations, and scheduler calculations.
+- Add component or end-to-end tests later when UI behavior becomes stable enough to justify them.
+
+## Comments
+
+- Prefer clear names and small functions over explanatory comments.
+- Add comments only where the reason is not obvious from the code.
+- Avoid comments that restate the next line of code.
+- Use comments to explain timing assumptions, loop-boundary decisions, browser audio constraints, or non-obvious model migrations.

docs/features/01-project-scaffold.md

@@ -1,7 +1,7 @@
 # Feature: 01 Project Scaffold
 
 ## Status
-In Review
+Complete
 
 ## Goal