Back to Details

project-setup

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Project Setup

项目初始化

Core Principles

核心原则

  • Strong Typing: Strict mode enabled; types catch bugs at compile time
  • Strong Linting: Strict rules by default; easier to disable than add later
  • Auto Formatting: Automated and consistent; no manual formatting
  • Checks at Every Stage: Pre-commit hooks + CI; catch issues early
  • Co-located Tests: 
    foo.ts
    → 
    foo.test.ts
    ; obvious what's tested
  • Behavior-Focused: Test what code does, not how; mock only external boundaries
  • 强类型检查：启用严格模式；在编译阶段通过类型检查捕获bug
  • 严格代码扫描：默认启用严格规则；禁用规则比后续添加更简单
  • 自动格式化：自动化且格式统一；无需手动调整格式
  • 全阶段检查：提交前钩子（Pre-commit hooks）+ 持续集成（CI）；尽早发现问题
  • 测试文件同目录存放：
    foo.ts
    → 
    foo.test.ts
    ；清晰知晓测试覆盖范围
  • 聚焦行为测试：测试代码的功能而非实现方式；仅对外部依赖进行模拟

Workflow

工作流程

  1. Check 
    reference/
    for language guide (Python, TypeScript)
  2. If no guide: WebSearch "[language] project setup best practices"
  3. Follow setup: typing → linting → formatting → testing → pre-commit → CI
  4. For existing projects: migrate incrementally in same order
  1. 查看
    reference/
    目录下的语言指南（Python、TypeScript）
  2. 若无对应指南：搜索“[语言] 项目初始化最佳实践”
  3. 按照以下顺序完成初始化：类型检查 → 代码扫描 → 格式化 → 测试 → 提交前钩子 → 持续集成（CI）
  4. 针对已有项目：按相同顺序逐步迁移

Reference Files

参考文件

  • reference/python.md
    - uv, ruff, basedpyright, pytest
  • reference/typescript.md
    - pnpm, ESLint, Prettier, Vitest
  • reference/common-patterns.md
    - Testing philosophy, CI patterns, security
  • reference/python.md
    - uv、ruff、basedpyright、pytest
  • reference/typescript.md
    - pnpm、ESLint、Prettier、Vitest
  • reference/common-patterns.md
    - 测试理念、CI模式、安全性

Tool Selection

工具选择

Prefer tools that are: ecosystem standard, actively maintained, strict by default, fast, well-integrated (editor + CI + pre-commit).
优先选择符合以下标准的工具：生态系统标准、维护活跃、默认严格、速度快、集成性好（编辑器 + CI + 提交前钩子）

Quality Checklist

质量检查清单

  • Typing: Strictest mode, no 
    any
    without justification
  • Linting: Strict rules, warnings as errors
  • Formatting: Auto-format on save + pre-commit
  • Testing: Co-located tests, coverage >80%
  • Pre-commit: Format, lint, type-check
  • CI: Same checks + coverage reporting
  • README: Setup instructions
  • All checks pass on initial commit
  • 类型检查：启用最严格模式，无合理理由不使用
    any
    类型
  • 代码扫描：严格规则，将警告视为错误
  • 格式化：保存时自动格式化 + 提交前检查
  • 测试：测试文件同目录存放，覆盖率>80%
  • 提交前钩子：格式化、代码扫描、类型检查
  • CI：执行相同检查 + 覆盖率报告
  • README：包含初始化说明
  • 首次提交时所有检查均通过