---
name: technical-spec
description: Defines environment variables, architecture design, and build/test commands. Use when configuring environment or designing architecture.
---

# Technical Design Rules

## Basic Technology Stack Policy
TypeScript-based application implementation. Architecture patterns should be selected according to project requirements and scale.

## Environment Variable Management and Security

### Environment Variable Management
- Centrally manage environment variables and build mechanisms to ensure type safety
- Avoid direct references to `process.env`, obtain through configuration management layer
- Properly implement default value settings and mandatory checks

### Security
- Do not include `.env` files in Git
- Always manage API keys and secrets as environment variables
- Prohibit logging of sensitive information
- Do not include sensitive information in error messages

## Architecture Design

### Architecture Design Principles
Select appropriate architecture for each project and define clearly:

- **Separation of Responsibilities**: Clearly define responsibilities for each layer and module, and maintain boundaries

## Unified Data Flow Principles

#### Basic Principles
1. **Single Data Source**: Store the same information in only one place
2. **Structured Data Priority**: Use parsed objects rather than JSON strings
3. **Clear Responsibility Separation**: Clearly define responsibilities for each layer

#### Data Flow Best Practices
- **Validation at Input**: Validate data at input layer and pass internally in type-safe form
- **Centralized Transformation**: Consolidate data transformation logic in dedicated utilities
- **Structured Logging**: Output structured logs at each stage of data flow

## Build and Testing
Use the appropriate run command based on the `packageManager` field in package.json.

### Build Commands
- `build` - TypeScript build
- `type-check` - Type check (no emit)

### Testing Commands
- `test` - Run tests
- `test:coverage` - Run tests with coverage
- `test:coverage:fresh` - Run tests with coverage (fresh cache)
- `test:safe` - Safe test execution (with auto cleanup)
- `cleanup:processes` - Cleanup Vitest processes

### Quality Assurance Mechanism Awareness

Before executing quality checks, identify what quality mechanisms exist for the change area:
- Primary detection: inspect the change area's file types, project manifest, and configuration to identify applicable quality tools
  - Check CI pipeline definitions for checks that cover the affected paths
  - Check for domain-specific linter or validator configurations (e.g., schema validators, API spec validators, configuration file linters)
  - Check for domain-specific constraints in project configuration (naming rules, length limits, format requirements)
- Supplementary hint: IF task file specifies Quality Assurance Mechanisms → use them as additional hints for which domain-specific checks to look for
- Include discovered domain-specific checks alongside standard quality phases below

### Quality Check Requirements

Quality checks are mandatory upon implementation completion:

**Phase 1-3: Code Quality Checks**
- Auto-detect and execute the following from package.json scripts:
  - lint + format check
  - Detect unused exports
  - Detect circular dependencies
  - TypeScript build

**Phase 4: Tests**
- `test` - Test execution

**Phase 5: Code Quality Re-verification**
- `check:code` - Re-verify code quality (clean up side effects from test fixes in Phase 4)

### Auxiliary Commands
- `check:all` - Overall integrated check (check:code + test) *for manual batch verification
- `open coverage/index.html` - Check coverage report
- `format` - Format fixes
- `lint:fix` - Lint fixes

### Troubleshooting
- **Port in use error**: Run the `cleanup:processes` script
- **Cache issues**: Run the `test:coverage:fresh` script
- **Dependency errors**: Clean reinstall dependencies

### Coverage
- Treat coverage as a diagnostic signal for finding untested areas, not a target (a target gets gamed into trivial tests — Goodhart's Law). Concentrate tests on critical paths and business logic whose regression would matter
- Any enforced numeric threshold is the project's CI/coverage config, not a goal in itself
- **Metrics** (what coverage reports break down): Statements, Branches, Functions, Lines