05-02 · 项目框架沉淀：你的专属 Starter

"每次新项目都从零开始" 是未来股东最容易掉进去的时间黑洞。真正的高手有一套属于自己的项目模板：每开新项目，第一天就能跑起来，第一周就能交付雏形。

---

一、为什么要有自己的 Starter

现象

• 新建一个 Python 项目 → 半天搭脚手架（venv、ruff、mypy、pytest、Makefile）
• 新建一个全栈项目 → 一天搭脚手架（前后端连接、CORS、auth、CI/CD）
• 每次都重复，且每次都不太一样

后果

• 时间被搭脚手架吞掉
• 每个项目质量不一致
• 同事接手时一句"我不熟悉你的脚手架"，让协作成本骤升

解决：starter 模板 + 公司模板

你的本地：~/projects/_starters/
├── py-fastapi-starter/      ← Python + FastAPI 后端
├── react-vite-starter/      ← React + Vite + shadcn 前端
├── monorepo-starter/        ← 全栈 monorepo
├── agent-product-starter/   ← Agent 产品起手式
└── mcp-server-starter/      ← MCP server 模板

---

二、每个 Starter 必须包含的 7 个文件

my-starter/
├── README.md          ← 项目目标、技术栈、运行方式
├── AGENTS.md          ← 给 AI Agent 的项目说明书
├── CLAUDE.md          ← 给 Claude Code 的指令（CLAUDE.md 优先级最高）
├── DESIGN.md          ← 设计系统（前端项目必备）
├── .env.example       ← 环境变量示例
├── Makefile           ← 公司统一约定的 make 命令
└── .github/
    └── workflows/
        └── ci.yml     ← CI 默认走 lint + test + build

AGENTS.md 模板（公司版）

# Project: {项目名}

## 一句话目标
{这个项目要解决什么问题，给谁用}

## 技术栈
- 后端：Python 3.11 + FastAPI
- 前端：React 19 + Vite + shadcn/ui
- 数据库：PostgreSQL 16
- 基础设施：Docker Compose（dev）/ Kubernetes（prod）

## 设计原则
1. 不重复造轮子。能用现成库的不自己写。
2. 类型先行。Python 必须 mypy strict，TS 必须 strict mode。
3. 先写测试 / 先写文档，再写代码。
4. 永远不要硬编码密钥。所有 secret 走环境变量。

## 必走的命令
- `make dev`：启动开发环境
- `make test`：跑测试
- `make lint`：跑 lint + format
- `make ship`：跑全套质量门槛 + commit + push

## 已知约束
- 时区统一 Asia/Shanghai
- 货币统一 CNY，单位统一"分"
- 所有 API 路径以 /api/v1 开头

## 给 AI 的话
- 修任何 bug 之前先复现
- 不要直接 push
- commit 必须按 qdy-commit Skill 的规范
- 涉及数据库变更必须写 migration

Makefile 模板（公司统一）

.PHONY: install dev test lint ship clean

install:
	uv sync && pnpm install

dev:
	docker compose up -d db
	uvicorn app.main:app --reload &
	pnpm --filter web dev

test:
	pytest -q
	pnpm --filter web test

lint:
	ruff check . && ruff format --check .
	mypy app
	pnpm --filter web lint

ship: lint test
	@echo "✅ all green, you may commit & push"

clean:
	rm -rf .venv node_modules dist build .pytest_cache

---

三、初始化新项目的标准流程

# 1. 复制 starter
cp -r ~/projects/_starters/py-fastapi-starter ~/projects/my-new-project
cd ~/projects/my-new-project

# 2. 让 Agent 帮你改名 / 重置
claude
> 这是我从 starter 复制的项目，请把项目名从 "{{name}}" 改成 "my-new-project"，
> 并按 AGENTS.md 里的"一句话目标"重新生成 README 第一段。
> 任务目标是：做一个客户线索打分服务。

# 3. 初始化 git
git init
git add . && git commit -m "chore: bootstrap from py-fastapi-starter"

# 4. 跑通 dev
make install
make dev

5 分钟你就能开始写业务代码了。

---

四、Starter 的迭代节奏

频率	动作
每个新项目结束	复盘："这次有哪些通用的部分应该回填到 starter？"
每月	看一次 starter 是否有过时依赖 / 过时模式
每季度	公司层面统一升级一波（最新 React、最新 FastAPI、最新工具链）

---

五、把 Starter 包成 cookiecutter / nx generator

Python：cookiecutter

pip install cookiecutter

# starter 改造为 cookiecutter 模板
~/projects/_starters/py-fastapi-starter/
├── cookiecutter.json   ← 变量定义
└── {{cookiecutter.project_slug}}/
    ├── README.md
    └── ...

# 使用
cookiecutter ~/projects/_starters/py-fastapi-starter
# → 交互问 project_name / author / db_name 等，自动填充

Node.js：create-* CLI 或 nx workspace

或者直接用 degit：

npx degit yourname/react-vite-starter my-app

---

六、公司模板仓库（建议结构）

qdy-starters/                  ← 公司组织内 git repo
├── README.md
├── catalog.md                 ← 模板清单
└── templates/
    ├── py-fastapi/
    ├── react-vite/
    ├── nextjs/
    ├── monorepo/
    ├── agent-product/
    └── mcp-server/

每位未来股东入职第一周必须：

1. clone 公司模板仓库
2. 跑一遍每个模板，至少能 make dev 起来
3. 选一个模板做 onboarding 项目

---

七、心法（必背）

第一遍做项目花 5 天，第二遍花 1 天，第三遍花 1 小时。这就叫"沉淀"。

如果你第三次做同类项目还要 5 天，说明你只是在重复劳动。

公司不希望任何人在重复劳动里浪费生命。做完每个项目，问自己：

• 这次有哪些可以 commit 回 starter？
• 有哪些可以抽成 Skill？
• 有哪些可以包成 MCP？

每次都要带着这三个问题离开项目现场。

---

继续 → 06 · Agent 产品体系