technical-spec

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