project-bootstrap

项目初始化

概述

正确初始化项目，可避免未来 80% 的结构性麻烦。

**核心原则：**现在花 30 分钟做好设置，或者以后花 30 小时偿还结构性债务。

没有例外。没有变通办法。没有捷径。

首要原则

NO FEATURE CODE BEFORE PROJECT STRUCTURE IS ESTABLISHED

如果项目缺少 lint、格式化、测试基础设施和版本控制规范，请先弥补这些不足，再编写任何业务逻辑。

适用场景

必须使用：

• 从零创建新项目
• “先让它跑起来再说”（尤其是这种情况）
• 构建可能发展为生产项目的原型
• 为团队设置共享仓库

同样适用：

• 接手一个没有结构基础的项目
• 为未经测试的代码补充测试基础设施
• 首次引入 CI/CD

入门流程

BEFORE writing any feature code:

1. STRUCTURE: Is the directory layout established?
2. TOOLING: Are linter, formatter, and type checker wired up?
3. TESTING: Is the test runner configured with a passing placeholder?
4. VERSION CONTROL: Are .gitignore, branch conventions, and hooks set up?
5. DEPENDENCIES: Is the package manager initialized with a committed lockfile?
6. AUTOMATION: Does at minimum a lint + test pipeline exist?

If any answer is NO: fix it first.

项目分类

digraph project_class {
    start [label="What is being\nbuilt?", shape=diamond];
    web [label="Web\napplication?", shape=diamond];
    api [label="API /\nbackend?", shape=diamond];
    cli [label="CLI tool?", shape=diamond];
    lib [label="Library /\npackage?", shape=diamond];

    web_tpl [label="Web App\nBlueprint", shape=box, style=filled, fillcolor="#ccffcc"];
    api_tpl [label="API\nBlueprint", shape=box, style=filled, fillcolor="#ccccff"];
    cli_tpl [label="CLI\nBlueprint", shape=box, style=filled, fillcolor="#ffffcc"];
    lib_tpl [label="Library\nBlueprint", shape=box, style=filled, fillcolor="#ffccff"];
    general [label="General\nBlueprint", shape=box, style=filled, fillcolor="#ffcccc"];

    start -> web [label="assess"];
    web -> web_tpl [label="yes"];
    web -> api [label="no"];
    api -> api_tpl [label="yes"];
    api -> cli [label="no"];
    cli -> cli_tpl [label="yes"];
    cli -> lib [label="no"];
    lib -> lib_tpl [label="yes"];
    lib -> general [label="no"];
}

请参阅 templates.md，了解各项目分类对应的详细设置清单。

通用基础（所有项目）

1. 版本控制规范

.gitignore          # Language-specific + universal exclusions
.gitattributes      # Line ending normalization, binary file handling

.gitignore 必须包含：

• node_modules/、venv/、__pycache__/、target/（依赖目录）
• .env、.env.local、.env.*.local（机密信息和凭据）
• *.log（日志文件）
• .DS_Store、Thumbs.db（操作系统生成的文件）
• IDE 目录：.idea/、.vscode/（除非有意共享设置）
• 构建输出：dist/、build/、out/

2. 静态分析和格式化

语言	Linter	格式化工具
TypeScript/JavaScript	ESLint	Prettier
Python	Ruff（lint + format）	Ruff
Go	golangci-lint	gofmt（内置）
Rust	clippy	rustfmt（内置）
Ruby	RuboCop	RuboCop

**第一天就安装。**写到 10,000 行后再采用 linter，意味着首次运行时就要处理数百条违规。

3. 测试基础设施

语言	框架	运行器
TypeScript/JavaScript	Vitest 或 Jest	内置
Python	pytest	内置
Go	testing（标准库）	go test
Rust	内置测试框架	cargo test
Ruby	RSpec 或 Minitest	内置

**立即编写一个能通过的测试。**这样可以在真正需要测试之前，确认测试流程能够正常运行。

4. 类型安全

语言	要求
TypeScript	在 tsconfig.json 中设置 strict: true。这是硬性要求。
Python	类型注解 + mypy 或 pyright
JavaScript	考虑使用 TypeScript。如果不使用，至少添加 JSDoc 类型注解。

5. 持续集成最低要求

每个项目至少必须包含：

# Minimum CI pipeline (GitHub Actions example)
on: [push, pull_request]
jobs:
  check:
    steps:
      - lint
      - type-check
      - test

如果某项检查没有在 CI 中运行，就不会得到维护。

目录结构原则

按功能组织，而不是按文件类型组织（参见 godmode:system-design）。

每个项目都必须包含：

project-root/
  src/              # Source code (or lib/, app/ per convention)
  tests/            # Test files (or co-located alongside source)
  docs/             # Documentation (when applicable)
  scripts/          # Build, deploy, and utility scripts
  .gitignore
  README.md         # Purpose, installation, how to run
  <config files>    # Linter, formatter, CI, package manager

测试与代码放在一起，还是放在单独目录：

• 放在一起（payment.ts + payment.test.ts）：更易维护，默认优先采用
• 单独放置（tests/）：当测试需要共享夹具，或团队规范要求这样做时采用

依赖治理

BEFORE adding any dependency:

1. Is it genuinely necessary? Could you write it in under 50 lines?
2. Is it actively maintained?
3. How many transitive dependencies does it introduce?
4. Does it carry known vulnerabilities?

When uncertain, write the code yourself.

务必：

• 提交锁文件（package-lock.json、poetry.lock、Cargo.lock）
• 固定主版本，允许补丁版本更新
• 在 CI 中执行安全审计

认知陷阱

自我安慰	真相
“这只是个原型”	原型会发展为生产项目。请正确初始化。
“以后再添加 lint”	写到 10,000 行后，你将面对数百条违规。现在处理总是更容易。
“测试会拖慢初期开发”	设置测试只需 5 分钟。没有测试时排查 Bug 要花数小时。
“这个项目没必要用 CI”	CI 能捕捉你忘记的事情。第一天就把它配置好。
“以后再整理文件”	你不会这么做。更改目录结构比更改代码难。
“.gitignore 可以稍后再配”	一旦提交了 .env 文件，凭据就会泄露。先配置好。

防护规则——停止并先完成基础配置

• 未配置代码检查工具就编写功能
• 仓库中没有 .gitignore
• 未安装测试框架
• 将机密提交到版本历史中（哪怕只提交过一次，即使之后删除，它们仍会保留在 git 历史中）
• 没有说明如何运行项目的 README
• 将构建产物提交到 git
• 没有 CI 流水线
• 到处都是 any 类型（TypeScript）

列表中的每一项都意味着：停止开发功能。先修好基础。

集成

互补技能：

• godmode:system-design ——目录结构与技术选型
• godmode:quality-enforcement ——从一开始就在 CI 中配置质量门禁
• godmode:security-protocol ——机密管理与 .gitignore 规范
• godmode:ux-patterns ——为 UI 项目初始化设计系统

总结

30 minutes of setup now > 30 hours of structural debt later

代码检查工具。格式化工具。测试。CI。.gitignore。README。先于第一个功能。每一次都如此。