gavindiaz/vibe-coding-cn
1
0
Fork 0
mirror of https://github.com/tradecatlabs/vibe-coding-cn.git synced 2026-07-27 18:57:50 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
develop
vibe-coding-cn/docs/references/project-architecture-template.md
T
tradecatlabs dddb9cd19b docs: split docs readmes into topic files
2026-06-01 00:48:27 +08:00

14 KiB
Raw Permalink Blame History

工程实践

项目架构、代码组织、开发经验、质量门禁与常见坑。

核心摘要

工程实践的核心目标是把“AI 可能写对”变成“系统必须可验证”：任务开始前写清目标、边界和验收标准；实现过程中用拼好码优先复用成熟方案；交付前用测试、CI、脚本、类型、schema、检查清单和代码审查形成硬门禁。

本文件适合作为开发者和 Agent 的工程约束手册：遇到架构设计、代码组织、质量门禁、常见坑、环境问题、Git 操作和项目维护时，优先在这里查规则和检查项。

顶部导航

主题 用途
项目架构模板 判断目录、模块、边界和职责是否清楚
代码组织 检查命名、分层、依赖、状态和可维护性
开发经验 沉淀任务推进、协作、复盘和交付经验
AI 编程质量门禁与常见坑 把验收标准转成测试、CI、脚本、类型、schema 或清单
底层程序逻辑设计与工程优化项 用运行、并发、数据、性能和可观测模型约束实现

使用方式

  • 新项目从「项目架构模板」开始，先确定目录、边界、门禁和检查清单。
  • 写代码前看「代码组织」与「开发经验」，统一命名、结构、职责和迭代方式。
  • 做实现、重构或性能排查前看「底层程序逻辑设计与工程优化项」，用运行模型、并发模型、数据模型和性能模型约束方案。
  • 使用 AI 编程时看「AI 编程质量门禁与常见坑」，把自然语言验收标准落到测试、CI、脚本、类型、schema 或检查清单。
  • 遇到问题时优先按本文档中的门禁和常见坑排查，不要直接进入盲目重写。

目录

1. 项目架构模板

1. 使用原则

项目架构不是先追求“高级感”，而是先回答这些问题：

  • 代码放哪里。
  • 模块怎么分工。
  • 数据怎么流动。
  • 依赖怎么隔离。
  • 如何测试、部署、回滚和维护。

默认顺序：

  1. 先确定交付物：页面、API、数据集、CLI、服务还是组合系统。
  2. 再确定边界：模块边界、数据边界、运行边界、外部依赖边界。
  3. 再确定目录：目录只服务于边界，不反过来制造复杂度。
  4. 最后补门禁：测试、lint、schema、配置示例、README、AGENTS。

2. 快速选型

项目类型 推荐模板
Python 应用 / 服务 / 脚本工具 / 库项目 通用 Python 项目骨架
Web API / 后端服务 Python Web/API 项目结构
数据分析 / 量化 / 机器学习 数据科学项目结构
多服务 / 大型系统 Monorepo 项目结构
中大型工程组织 / 平台工程 / 多产品线 企业级 Monorepo / Multi-repo 项目架构标准模板
前后端一体项目 Full-Stack Web 应用结构
长期运行的数据采集服务 Dataset First 数据服务结构

3. Python Web/API 项目结构

适合 Flask、FastAPI、RESTful API、Web 后端服务。

project/
├── README.md
├── AGENTS.md
├── LICENSE
├── pyproject.toml
├── requirements.txt
├── .env.example
├── .gitignore
├── docs/
│   ├── api.md
│   ├── architecture.md
│   └── development.md
├── scripts/
│   ├── deploy.sh
│   ├── backup.sh
│   └── init_db.sh
├── tests/
│   ├── conftest.py
│   ├── unit/
│   └── integration/
├── src/
│   ├── main.py
│   ├── app.py
│   ├── config.py
│   ├── api/
│   │   ├── v1/
│   │   └── dependencies.py
│   ├── core/
│   │   ├── models/
│   │   ├── services/
│   │   └── utils/
│   ├── data/
│   │   ├── repository/
│   │   └── migrations/
│   └── external/
│       ├── clients/
│       └── integrations/
├── data/                 # 不提交，或只提交 README/.gitkeep
└── logs/                 # 不提交，或只提交 README/.gitkeep

关键边界：

  • api/ 只处理协议、路由、参数校验和响应格式。
  • core/services/ 承载业务逻辑。
  • data/repository/ 隔离数据库访问。
  • external/ 隔离第三方 API、SDK 和平台依赖。
  • .env 不提交，必须提供 .env.example。

4. 数据科学 / 量化项目结构

适合量化交易、机器学习、数据分析、AI 研究。

project/
├── README.md
├── AGENTS.md
├── LICENSE
├── pyproject.toml
├── requirements.txt
├── .env.example
├── .gitignore
├── docs/
│   ├── notebooks/
│   └── reports/
├── notebooks/
│   ├── 01_data_exploration.ipynb
│   ├── 02_feature_engineering.ipynb
│   └── 03_model_training.ipynb
├── scripts/
│   ├── collect_data.py
│   ├── train_model.py
│   ├── backtest.py
│   └── deploy_model.py
├── tests/
│   ├── test_data/
│   └── test_models/
├── configs/
│   ├── model.yaml
│   ├── database.yaml
│   └── trading.yaml
├── src/
│   ├── data/
│   │   ├── collectors/
│   │   ├── processors/
│   │   ├── features/
│   │   └── loaders.py
│   ├── models/
│   │   ├── strategies/
│   │   ├── backtest/
│   │   └── risk/
│   ├── core/
│   │   ├── config.py
│   │   ├── signals.py
│   │   └── portfolio.py
│   └── utils/
│       ├── logging.py
│       ├── database.py
│       └── api_client.py
├── data/                 # 不提交大数据文件
├── models/               # 不提交大模型/大 checkpoint
└── logs/

关键边界：

  • Notebook 用于探索，不作为长期生产入口。
  • scripts/ 是薄入口，核心逻辑应在 src/。
  • 数据、模型、日志默认不进 Git，除非是小型示例或 fixture。
  • 回测、训练、采集、部署脚本必须能复现关键参数。

5. Monorepo 项目结构

适合多服务架构、大型项目、团队协作。

project-monorepo/
├── README.md
├── AGENTS.md
├── LICENSE
├── .gitignore
├── .gitmodules
├── docker-compose.yml
├── docs/
│   ├── architecture.md
│   └── deployment.md
├── scripts/
│   ├── build_all.sh
│   ├── test_all.sh
│   └── deploy.sh
├── services/
│   ├── user-service/
│   │   ├── Dockerfile
│   │   ├── pyproject.toml
│   │   ├── src/
│   │   └── tests/
│   ├── trading-service/
│   └── data-service/
├── packages/
│   ├── common/
│   └── contracts/
├── infrastructure/
│   ├── terraform/
│   ├── kubernetes/
│   └── nginx/
└── monitoring/
    ├── prometheus/
    ├── grafana/
    └── alertmanager/

关键边界：

  • 每个 services/* 应能独立构建、测试和部署。
  • 公共能力放 packages/，不要让服务之间互相直接 import 私有实现。
  • contracts/ 存 API schema、事件 schema、数据契约，作为跨服务真相源。
  • 顶层脚本只做编排，不隐藏服务内部逻辑。

6. Full-Stack Web 应用结构

适合 SPA、前后端分离项目、轻量产品原型。

project/
├── README.md
├── AGENTS.md
├── LICENSE
├── .gitignore
├── docker-compose.yml
├── docs/
│   ├── architecture.md
│   └── deployment.md
├── frontend/
│   ├── package.json
│   ├── vite.config.js
│   ├── public/
│   └── src/
│       ├── components/
│       ├── pages/
│       ├── store/
│       └── utils/
└── backend/
    ├── Dockerfile
    ├── pyproject.toml
    ├── src/
    │   ├── api/
    │   ├── core/
    │   └── models/
    └── tests/

关键边界：

  • 前端状态管理不要直接绑定后端数据库结构。
  • 后端 API contract 应有 schema 或类型定义。
  • 前后端共享类型时，优先从 OpenAPI、JSON Schema 或生成工具派生。

8. 架构设计原则

关注点分离
API -> Service -> Repository -> Database / External System

上层可以调用下层，下层不能反向依赖上层。

可测试性
  • 每个模块可独立测试。
  • 外部依赖可 mock。
  • 核心业务逻辑不依赖 CLI、HTTP、数据库连接对象。

可配置性
环境变量 > 配置文件 > 默认值

配置与代码分离，敏感配置不得提交。

可维护性
  • 文件名表达职责。
  • 目录边界表达模块边界。
  • 业务逻辑、平台适配、第三方依赖隔离。

版本控制友好
  • data/、logs/、models/ 默认加入 .gitignore。
  • 大文件不进 Git，必要时使用对象存储、Release、DVC 或外部数据源。
  • 提交源代码、配置示例、文档、测试和小型 fixture。

9. 最低门禁

代码门禁
  • 语法检查通过。
  • 单元测试覆盖核心业务。
  • lint/format 有明确命令。
  • 关键路径纳入版本控制。

结构门禁
  • 不允许临时脚本成为长期入口。
  • 不允许同一职责存在多套实现入口。
  • 不允许外部 SDK 类型污染核心业务模型。
  • 数据服务不允许新逻辑回流 legacy 壳。

运行门禁
  • 服务能按 README 启动。
  • stop -> start -> status -> restart -> status 可验证。
  • 日志能证明真实执行源。
  • PID、log、run metadata 可追踪。

数据门禁
  • 每个 active dataset 至少有 contract + writer + collect 或 backfill。
  • resource_id 与 registry 一致。
  • 质量检查至少覆盖空写、重复写、时间边界、幂等。

文档门禁
  • README 说明项目定位、安装、启动、测试和目录结构。
  • AGENTS 说明 AI Agent 修改边界、验证命令和禁止事项。
  • .env.example 说明必要配置。
  • 架构变化同步更新文档。

10. .gitignore 推荐模板

# Python
__pycache__/
*.py[cod]
*.egg-info/
dist/
build/

# Environment
.env
.venv/
env/
venv/

# IDE
.vscode/
.idea/
*.swp
*.swo
*~
.DS_Store

# Data
data/
*.csv
*.db
*.sqlite
*.duckdb

# Logs
logs/
*.log

# Models
models/
*.h5
*.pkl
*.pt
*.onnx

# Temporary
tmp/
temp/
*.tmp

11. 技术选型参考

场景 推荐技术栈
Web API FastAPI + Pydantic + SQLAlchemy
数据处理 Pandas + NumPy + Polars
机器学习 Scikit-learn + XGBoost + LightGBM
深度学习 PyTorch / TensorFlow
数据库 PostgreSQL + Redis
消息队列 RabbitMQ / Kafka
任务队列 Celery
监控 Prometheus + Grafana
部署 Docker + Docker Compose
CI/CD GitHub Actions / GitLab CI

12. 新项目检查清单

  • 创建 README.md，说明项目目标、安装、启动、测试。
  • 创建 AGENTS.md，说明 AI Agent 操作边界与必须验证命令。
  • 创建 LICENSE。
  • 创建 .gitignore。
  • 创建 .env.example。
  • 建立虚拟环境或包管理配置。
  • 明确目录结构。
  • 明确配置入口。
  • 设置 lint/format/test 命令。
  • 编写第一个测试用例。
  • 记录架构决策和后续 TODO。

13. 常见反模式

  • 一开始就做微服务。
  • 所有代码写在一个文件。
  • 架构追求高级感，而不是可维护。
  • 没想清楚数据流就开始写。
  • 目录按技术名堆砌，但没有业务边界。
  • 业务逻辑直接依赖第三方 SDK。
  • 临时脚本长期成为生产入口。
  • 数据服务没有 registry，dataset 清单散落在脚本里。
  • 先写采集器，再倒推表结构。
  • 每个 dataset 各自实现 start/status/restart。

14. 一句话结论

项目架构的目标不是把目录做复杂，而是让职责、数据流、依赖和验证路径清楚。普通项目先选通用结构；稳定数据服务优先采用 Dataset First，用 contract、registry、runtime 和质量门禁固定长期演进边界。

Reference in New Issue View Git Blame Copy Permalink