mirror of
https://github.com/tradecatlabs/vibe-coding-cn.git
synced 2026-08-21 23:08:06 +00:00
fix(en): correct file locations to match zh structure
- Move Code Organization.md, General Project Architecture Template.md to 00-fundamentals - Move Learning Experience.md, Gemini Headless..., vibe-coding-experience... to 02-methodology - Update README files
This commit is contained in:
tukuaiai
@@ -0,0 +1,45 @@
|
||||
# Code Organization
|
||||
|
||||
## Modular Programming
|
||||
|
||||
- Divide code into small, reusable modules or functions, with each module responsible for doing only one thing.
|
||||
- Use clear modular structures and directory structures to organize code, making it easier to navigate.
|
||||
|
||||
## Naming Conventions
|
||||
|
||||
- Use meaningful and consistent naming conventions so that the purpose of variables, functions, and classes can be understood from their names.
|
||||
- Follow naming conventions, such as CamelCase for class names and snake_case for function and variable names.
|
||||
|
||||
## Code Comments
|
||||
|
||||
- Add comments to complex code segments to explain the code's functionality and logic.
|
||||
- Use block comments (/*...*/) and line comments (//) to distinguish between different types of comments.
|
||||
|
||||
## Code Formatting
|
||||
|
||||
- Use consistent code style and formatting rules, and use tools like Prettier or Black to automatically format code.
|
||||
- Use blank lines, indentation, and spaces to increase code readability.
|
||||
|
||||
# Documentation
|
||||
|
||||
## Docstrings
|
||||
|
||||
- Use docstrings at the beginning of each module, class, and function to explain its purpose, parameters, and return values.
|
||||
- Choose a consistent docstring format, such as Google Style, NumPy/SciPy Style, or Sphinx Style.
|
||||
|
||||
## Automated Document Generation
|
||||
|
||||
- Use tools like Sphinx, Doxygen, or JSDoc to automatically generate documentation from code.
|
||||
- Keep documentation and code synchronized to ensure documentation is always up-to-date.
|
||||
|
||||
## README File
|
||||
|
||||
- Include a detailed README file in the root directory of each project, explaining the project's purpose, installation steps, usage, and examples.
|
||||
- Write README files using Markdown syntax to make them easy to read and maintain.
|
||||
|
||||
# Tools
|
||||
|
||||
## IDE
|
||||
|
||||
- Use powerful IDEs such as Visual Studio Code, PyCharm, or IntelliJ, leveraging their code auto-completion, error checking, and debugging features.
|
||||
- Configure IDE plugins, such as linters (e.g., ESLint, Pylint) and code formatters.
|
||||
@@ -1,42 +0,0 @@
|
||||
# Gemini Headless Mode Translation Guide
|
||||
|
||||
Objective: To perform non-interactive bulk translation locally using Gemini CLI (gemini-2.5-flash), avoiding tool calls and permission pop-ups, suitable for quick machine translation drafts of prompts/skills/documents.
|
||||
|
||||
## Principle Overview
|
||||
- CLI connects directly to Gemini API using locally cached Google credentials; model inference is done in the cloud.
|
||||
- Use `--allowed-tools ''` to disable tool calls, ensuring only plain text is returned, without triggering shell/browser actions.
|
||||
- Pass text to be translated via standard input, and get results from standard output, facilitating script pipeline processing.
|
||||
- A proxy (http/https) can be set to route requests through a local proxy node, improving success rate and stability.
|
||||
|
||||
## Basic Commands
|
||||
```bash
|
||||
# Proxy (if needed)
|
||||
export http_proxy=http://127.0.0.1:9910
|
||||
export https_proxy=http://127.0.0.1:9910
|
||||
|
||||
# Single example: Chinese -> English
|
||||
printf '你好，翻译成英文。' | gemini -m gemini-2.5-flash \
|
||||
--output-format text \
|
||||
--allowed-tools '' \
|
||||
"Translate this to English."
|
||||
```
|
||||
- The prompt can be placed as a positional argument (`-p/--prompt` is deprecated).
|
||||
- Output is plain text, can be redirected for saving.
|
||||
|
||||
## Batch File Translation Example (stdin → stdout)
|
||||
```bash
|
||||
src=i18n/zh/prompts/README.md
|
||||
dst=i18n/en/prompts/README.md
|
||||
cat "$src" | gemini -m gemini-2.5-flash --output-format text --allowed-tools '' \
|
||||
"Translate to English; keep code fences unchanged." > "$dst"
|
||||
```
|
||||
- Can loop through multiple files in a script; check exit code and output on failure.
|
||||
|
||||
## Integration with existing l10n-tool
|
||||
- l10n-tool (deep-translator) is used for full machine translation; if quality or connectivity is unstable, it can be switched to file-by-file processing with Gemini CLI.
|
||||
- Process: `cat source_file | gemini ... > target_file`; if necessary, place redirection instructions or manually proofread in other language directories.
|
||||
|
||||
## Notes
|
||||
- Ensure `gemini` command is in PATH and identity authentication is complete (first run will guide login).
|
||||
- For long texts, it is recommended to split them into segments to avoid timeouts; code blocks can be kept as is by declaring "keep code fences unchanged" in the prompt.
|
||||
- Adjust proxy port according to actual environment; if no proxy is needed, omit relevant environment variables.
|
||||
@@ -0,0 +1,695 @@
|
||||
# General Project Architecture Template
|
||||
|
||||
## 1️⃣ Standard Structure for Python Web/API Projects
|
||||
|
||||
```
|
||||
project_name/
|
||||
├── README.md # Project README
|
||||
├── LICENSE # Open-source license
|
||||
├── requirements.txt # Dependency management (pip)
|
||||
├── pyproject.toml # Modern Python project configuration (recommended)
|
||||
├── setup.py # Package installation script (if packaged as a library)
|
||||
├── .gitignore # Git ignore file
|
||||
├── .env # Environment variables (not committed to Git)
|
||||
├── .env.example # Example environment variables
|
||||
├── CLAUDE.md # Claude persistent context
|
||||
├── AGENTS.md # Codex persistent context
|
||||
├── Sublime-Text.txt # For requirements and notes, for self-reference, and CLI session recovery commands ^_^
|
||||
│
|
||||
├── docs/ # Documentation directory
|
||||
│ ├── api.md # API documentation
|
||||
│ ├── development.md # Development guide
|
||||
│ └── architecture.md # Architecture description
|
||||
│
|
||||
├── scripts/ # Script tools
|
||||
│ ├── deploy.sh # Deployment script
|
||||
│ ├── backup.sh # Backup script
|
||||
│ └── init_db.sh # Database initialization
|
||||
│
|
||||
├── tests/ # Test code
|
||||
│ ├── __init__.py
|
||||
│ ├── conftest.py # pytest configuration
|
||||
│ ├── unit/ # Unit tests
|
||||
│ ├── integration/ # Integration tests
|
||||
│ └── test_config.py # Configuration tests
|
||||
│
|
||||
├── src/ # Source code (recommended)
|
||||
│ ├── __init__.py
|
||||
│ ├── main.py # Program entry point
|
||||
│ ├── app.py # Flask/FastAPI application
|
||||
│ ├── config.py # Configuration management
|
||||
│ │
|
||||
│ ├── core/ # Core business logic
|
||||
│ │ ├── __init__.py
|
||||
│ │ ├── models/ # Data models
|
||||
│ │ ├── services/ # Business services
|
||||
│ │ └── utils/ # Utility functions
|
||||
│ │
|
||||
│ ├── api/ # API interface layer
|
||||
│ │ ├── __init__.py
|
||||
│ │ ├── v1/ # Version 1
|
||||
│ │ └── dependencies.py
|
||||
│ │
|
||||
│ ├── data/ # Data processing
|
||||
│ │ ├── __init__.py
|
||||
│ │ ├── repository/ # Data access layer
|
||||
│ │ └── migrations/ # Database migrations
|
||||
│ │
|
||||
│ └── external/ # External services
|
||||
│ ├── __init__.py
|
||||
│ ├── clients/ # API clients
|
||||
│ └── integrations/ # Integration services
|
||||
│
|
||||
├── logs/ # Log directory (not committed to Git)
|
||||
│ ├── app.log
|
||||
│ └── error.log
|
||||
│
|
||||
└── data/ # Data directory (not committed to Git)
|
||||
├── raw/ # Raw data
|
||||
├── processed/ # Processed data
|
||||
└── cache/ # Cache
|
||||
```
|
||||
|
||||
**Use Cases**: Flask/FastAPI Web applications, RESTful API services, Web backends
|
||||
|
||||
---
|
||||
|
||||
## 2️⃣ Standard Structure for Data Science/Quant Projects
|
||||
|
||||
```
|
||||
project_name/
|
||||
├── README.md
|
||||
├── LICENSE
|
||||
├── requirements.txt
|
||||
├── .gitignore
|
||||
├── .env
|
||||
├── .env.example
|
||||
├── CLAUDE.md # Claude persistent context
|
||||
├── AGENTS.md # Codex persistent context
|
||||
├── Sublime-Text.txt # For requirements and notes, for self-reference, and CLI session recovery commands ^_^
|
||||
│
|
||||
├── docs/ # Documentation directory
|
||||
│ ├── notebooks/ # Jupyter documentation
|
||||
│ └── reports/ # Analysis reports
|
||||
│
|
||||
├── notebooks/ # Jupyter Notebook
|
||||
│ ├── 01_data_exploration.ipynb
|
||||
│ ├── 02_feature_engineering.ipynb
|
||||
│ └── 03_model_training.ipynb
|
||||
│
|
||||
├── scripts/ # Script tools
|
||||
│ ├── train_model.py # Training script
|
||||
│ ├── backtest.py # Backtest script
|
||||
│ ├── collect_data.py # Data collection
|
||||
│ └── deploy_model.py # Model deployment
|
||||
│
|
||||
├── tests/ # Tests
|
||||
│ ├── test_data/
|
||||
│ └── test_models/
|
||||
│
|
||||
├── configs/ # Configuration files
|
||||
│ ├── model.yaml
|
||||
│ ├── database.yaml
|
||||
│ └── trading.yaml
|
||||
│
|
||||
├── src/ # Source code
|
||||
│ ├── __init__.py
|
||||
│ │
|
||||
│ ├── data/ # Data processing module
|
||||
│ │ ├── __init__.py
|
||||
│ │ ├── collectors/ # Data collectors
|
||||
│ │ ├── processors/ # Data cleaning
|
||||
│ │ ├── features/ # Feature engineering
|
||||
│ │ └── loaders.py # Data loaders
|
||||
│ │
|
||||
│ ├── models/ # Model module
|
||||
│ │ ├── __init__.py
|
||||
│ │ ├── strategies/ # Trading strategies
|
||||
│ │ ├── backtest/ # Backtest engine
|
||||
│ │ └── risk/ # Risk management
|
||||
│ │
|
||||
│ ├── utils/ # Utility module
|
||||
│ │ ├── __init__.py
|
||||
│ │ ├── logging.py # Log configuration
|
||||
│ │ ├── database.py # Database tools
|
||||
│ │ └── api_client.py # API client
|
||||
│ │
|
||||
│ └── core/ # Core module
|
||||
│ ├── __init__.py
|
||||
│ ├── config.py # Configuration management
|
||||
│ ├── signals.py # Signal generation
|
||||
│ └── portfolio.py # Portfolio
|
||||
│
|
||||
├── data/ # Data directory (Git ignored)
|
||||
│ ├── raw/ # Raw data
|
||||
│ ├── processed/ # Processed data
|
||||
│ ├── external/ # External data
|
||||
│ └── cache/ # Cache
|
||||
│
|
||||
├── models/ # Model files (Git ignored)
|
||||
│ ├── checkpoints/ # Checkpoints
|
||||
│ └── exports/ # Exported models
|
||||
│
|
||||
└── logs/ # Logs (Git ignored)
|
||||
├── trading.log
|
||||
└── errors.log
|
||||
```
|
||||
|
||||
**Use Cases**: Quantitative trading, machine learning, data analysis, AI research
|
||||
|
||||
---
|
||||
|
||||
## 3️⃣ Monorepo (Multi-Project Repository) Standard Structure
|
||||
|
||||
```
|
||||
project_name-monorepo/
|
||||
├── README.md
|
||||
├── LICENSE
|
||||
├── .gitignore
|
||||
├── .gitmodules # Git submodules
|
||||
├── docker-compose.yml # Docker orchestration
|
||||
├── CLAUDE.md # Claude persistent context
|
||||
├── AGENTS.md # Codex persistent context
|
||||
├── Sublime-Text.txt # This is a file, for requirements and notes, for self-reference, and CLI session recovery commands ^_^
|
||||
│
|
||||
├── docs/ # Global documentation
|
||||
│ ├── architecture.md
|
||||
│ └── deployment.md
|
||||
│
|
||||
├── scripts/ # Global scripts
|
||||
│ ├── build_all.sh
|
||||
│ ├── test_all.sh
|
||||
│ └── deploy.sh
|
||||
│
|
||||
├── backups/ # Backup files
|
||||
│ ├── archive/ # Old backup files
|
||||
│ └── gz/ # Gzip backup files
|
||||
│
|
||||
├── services/ # Microservice directory
|
||||
│ │
|
||||
│ ├── user-service/ # User service
|
||||
│ │ ├── Dockerfile
|
||||
│ │ ├── requirements.txt
|
||||
│ │ ├── src/
|
||||
│ │ └── tests/
|
||||
│ │
|
||||
│ ├── trading-service/ # Trading service
|
||||
│ │ ├── Dockerfile
|
||||
│ │ ├── requirements.txt
|
||||
│ │ ├── src/
|
||||
│ │ └── tests/
|
||||
│ ...
|
||||
│ └── data-service/ # Data service
|
||||
│ ├── Dockerfile
|
||||
│ ├── requirements.txt
|
||||
│ ├── src/
|
||||
│ └── tests/
|
||||
│
|
||||
├── libs/ # Shared libraries
|
||||
│ ├── common/ # Common modules
|
||||
│ │ ├── utils/
|
||||
│ │ └── models/
|
||||
│ ├── external/ # Third-party libraries (immutable, call only)
|
||||
│ └── database/ # Database access library
|
||||
│
|
||||
├── infrastructure/ # Infrastructure
|
||||
│ ├── terraform/ # Cloud resource definition
|
||||
│ ├── kubernetes/ # K8s configuration
|
||||
│ └── nginx/ # Reverse proxy configuration
|
||||
│
|
||||
└── monitoring/ # Monitoring system
|
||||
├── prometheus/ # Metrics collection
|
||||
├── grafana/ # Visualization
|
||||
└── alertmanager/ # Alerts
|
||||
```
|
||||
|
||||
**Use Cases**: Microservice architecture, large projects, team collaboration
|
||||
|
||||
---
|
||||
|
||||
## 4️⃣ Standard Structure for Full-Stack Web Applications
|
||||
|
||||
```
|
||||
project_name/
|
||||
├── README.md
|
||||
├── LICENSE
|
||||
├── .gitignore
|
||||
├── docker-compose.yml # Frontend and backend orchestration
|
||||
├── CLAUDE.md # Claude persistent context
|
||||
├── AGENTS.md # Codex persistent context
|
||||
├── Sublime-Text.txt # This is a file, for requirements and notes, for self-reference, and CLI session recovery commands ^_^
|
||||
│
|
||||
├── frontend/ # Frontend directory
|
||||
│ ├── public/ # Static assets
|
||||
│ ├── src/ # Source code
|
||||
│ │ ├── components/ # React/Vue components
|
||||
│ │ ├── pages/ # Pages
|
||||
│ │ ├── store/ # State management
|
||||
│ │ └── utils/ # Utilities
|
||||
│ ├── package.json # NPM dependencies
|
||||
│ └── vite.config.js # Build configuration
|
||||
│
|
||||
└── backend/ # Backend directory
|
||||
├── requirements.txt
|
||||
├── Dockerfile
|
||||
├── src/
|
||||
│ ├── api/ # API interfaces
|
||||
│ ├── core/ # Business logic
|
||||
│ │ └── models/ # Data models
|
||||
└── tests/
|
||||
```
|
||||
|
||||
**Use Cases**: Full-stack applications, SPA single-page applications, frontend/backend separated projects
|
||||
|
||||
---
|
||||
|
||||
## 📌 Core Design Principles
|
||||
|
||||
### 1. Separation of Concerns
|
||||
```
|
||||
API → Service → Data Access → Database
|
||||
Clear at a glance, clear hierarchy
|
||||
```
|
||||
|
||||
### 2. Testability
|
||||
```
|
||||
Each module is independently testable
|
||||
Dependencies can be mocked
|
||||
```
|
||||
|
||||
### 3. Configurability
|
||||
```
|
||||
Configuration separated from code
|
||||
Environment variables > Configuration files > Default values
|
||||
```
|
||||
|
||||
### 4. Maintainability
|
||||
```
|
||||
Self-documenting code
|
||||
Reasonable file naming
|
||||
Clear directory structure
|
||||
```
|
||||
|
||||
### 5. Version Control Friendly (Git-Friendly)
|
||||
```
|
||||
data/, logs/, models/ added to .gitignore
|
||||
Only commit source code and configuration examples
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Best Practice Recommendations
|
||||
|
||||
1. **Use `src/` directory**: Place source code in a dedicated `src` directory to avoid top-level clutter.
|
||||
2. **Relative imports**: Consistently use `from src.module import thing` for imports.
|
||||
3. **Test coverage**: Ensure core business logic has unit and integration tests.
|
||||
4. **Document first**: Write `README.md` for important modules.
|
||||
5. **Environment isolation**: Use virtualenv or conda to create isolated environments.
|
||||
6. **Explicit dependencies**: All dependencies written to `requirements.txt` and versions locked.
|
||||
7. **Configuration management**: Use a combination of environment variables + configuration files.
|
||||
8. **Logging levels**: DEBUG, INFO, WARNING, ERROR, FATAL.
|
||||
9. **Error handling**: Do not swallow exceptions; have a complete error chain.
|
||||
10. **Code style**: Use black for formatting, flake8 for checking.
|
||||
|
||||
---
|
||||
|
||||
## 🔥 .gitignore Recommended Template
|
||||
|
||||
```gitignore
|
||||
# Python
|
||||
__pycache__/
|
||||
*.py[cod]
|
||||
*$py.class
|
||||
*.so
|
||||
.Python
|
||||
*.egg-info/
|
||||
dist/
|
||||
build/
|
||||
|
||||
# Environment
|
||||
.env
|
||||
.venv/
|
||||
env/
|
||||
venv/
|
||||
ENV/
|
||||
|
||||
# IDE
|
||||
.vscode/
|
||||
.idea/
|
||||
*.swp
|
||||
*.swo
|
||||
*~
|
||||
|
||||
# Data
|
||||
data/
|
||||
*.csv
|
||||
*.json
|
||||
*.db
|
||||
*.sqlite
|
||||
*.duckdb
|
||||
|
||||
# Logs
|
||||
logs/
|
||||
*.log
|
||||
|
||||
# Models
|
||||
models/
|
||||
*.h5
|
||||
*.pkl
|
||||
|
||||
# Temporary files
|
||||
tmp/
|
||||
temp/
|
||||
*.tmp
|
||||
.DS_Store
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📚 Technology Selection Reference
|
||||
|
||||
| Scenario | Recommended Tech Stack |
|
||||
| :------- | :--------------------- |
|
||||
| Web API | FastAPI + Pydantic + SQLAlchemy |
|
||||
| Data Processing | Pandas + NumPy + Polars |
|
||||
| Machine Learning | Scikit-learn + XGBoost + LightGBM |
|
||||
| Deep Learning | PyTorch + TensorFlow |
|
||||
| Databases | PostgreSQL + Redis |
|
||||
| Message Queue | RabbitMQ / Kafka |
|
||||
| Task Queue | Celery |
|
||||
| Monitoring | Prometheus + Grafana |
|
||||
| Deployment | Docker + Docker Compose |
|
||||
| CI/CD | GitHub Actions / GitLab CI |
|
||||
|
||||
---
|
||||
|
||||
## 📝 File Template Examples
|
||||
|
||||
### requirements.txt
|
||||
```txt
|
||||
# Core dependencies
|
||||
fastapi==0.104.1
|
||||
uvicorn[standard]==0.24.0
|
||||
pydantic==2.5.0
|
||||
|
||||
# Database
|
||||
sqlalchemy==2.0.23
|
||||
alembic==1.12.1
|
||||
psycopg2-binary==2.9.9
|
||||
|
||||
# Testing
|
||||
pytest==7.4.3
|
||||
pytest-cov==4.1.0
|
||||
pytest-asyncio==0.21.1
|
||||
|
||||
# Utilities
|
||||
python-dotenv==1.0.0
|
||||
loguru==0.7.2
|
||||
|
||||
# Development (optional)
|
||||
black==23.11.0
|
||||
flake8==6.1.0
|
||||
mypy==1.7.1
|
||||
```
|
||||
|
||||
### pyproject.toml (Recommended for modern Python projects)
|
||||
```toml
|
||||
[project]
|
||||
name = "Project Name"
|
||||
version = "0.1.0"
|
||||
description = "Project Description"
|
||||
authors = [{name = "Author", email = "email@example.com"}]
|
||||
dependencies = [
|
||||
"fastapi>=0.104.0",
|
||||
"uvicorn[standard]>=0.24.0",
|
||||
"sqlalchemy>=2.0.0",
|
||||
]
|
||||
|
||||
[project.optional-dependencies]
|
||||
dev = ["pytest", "black", "flake8", "mypy"]
|
||||
|
||||
[build-system]
|
||||
requires = ["setuptools", "wheel"]
|
||||
build-backend = "setuptools.build_meta"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ✅ New Project Checklist
|
||||
|
||||
When starting a new project, ensure the following are completed:
|
||||
|
||||
- [ ] Create README.md, including project overview and usage instructions.
|
||||
- [ ] Create LICENSE file, clarifying the open-source license.
|
||||
- [ ] Set up Python virtual environment (venv/conda).
|
||||
- [ ] Create requirements.txt and lock dependency versions.
|
||||
- [ ] Create .gitignore, excluding sensitive and unnecessary files.
|
||||
- [ ] Create .env.example, explaining required environment variables.
|
||||
- [ ] Design directory structure, adhering to the principle of separation of concerns.
|
||||
- [ ] Create basic configuration files.
|
||||
- [ ] Set up code formatter (black).
|
||||
- [ ] Set up code checker (flake8/ruff).
|
||||
- [ ] Write the first test case.
|
||||
- [ ] Set up Git repository and commit initial code.
|
||||
- [ ] Create CHANGELOG.md, recording version changes.
|
||||
|
||||
---
|
||||
|
||||
In **programming / software development**, **Project Architecture / Software Architecture** refers to:
|
||||
|
||||
> **The design solution for how a project is broken down, organized, communicated, and evolved at the "overall level"**
|
||||
> —it determines how code is layered, how modules are divided, how data flows, and how the system expands and is maintained.
|
||||
|
||||
---
|
||||
|
||||
## One-Sentence Understanding
|
||||
|
||||
**Project Architecture = Deciding "where the code goes, how modules connect, and how responsibilities are divided" before writing any specific business code.**
|
||||
|
||||
---
|
||||
|
||||
## I. What Problems Does Project Architecture Primarily Solve?
|
||||
|
||||
Project architecture is not about "coding skills," but about solving these **higher-level problems**:
|
||||
|
||||
* 📦 How to organize code to avoid chaos?
|
||||
* 🔁 How do modules communicate?
|
||||
* 🧱 Which parts can be modified independently without affecting the whole?
|
||||
* 🚀 How will the project be extended in the future?
|
||||
* 🧪 How to facilitate testing, debugging, and deployment?
|
||||
* 👥 How to collaborate without stepping on each other's code?
|
||||
|
||||
---
|
||||
|
||||
## II. What Does Project Architecture Generally Include?
|
||||
|
||||
### 1️⃣ Directory Structure (Most Intuitive)
|
||||
|
||||
```text
|
||||
project/
|
||||
├── src/
|
||||
│ ├── main/
|
||||
│ ├── services/
|
||||
│ ├── models/
|
||||
│ ├── utils/
|
||||
│ └── config/
|
||||
├── tests/
|
||||
├── docs/
|
||||
└── README.md
|
||||
```
|
||||
|
||||
👉 Determines **"where different types of code are placed"**.
|
||||
|
||||
---
|
||||
|
||||
### 2️⃣ Layered Design (Core)
|
||||
|
||||
The most common is **Layered Architecture**:
|
||||
|
||||
```text
|
||||
Presentation Layer (UI / API)
|
||||
↓
|
||||
Business Logic Layer (Service)
|
||||
↓
|
||||
Data Access Layer (DAO / Repository)
|
||||
↓
|
||||
Database / External Systems
|
||||
```
|
||||
|
||||
**Rules:**
|
||||
|
||||
* Upper layers can call lower layers.
|
||||
* Lower layers cannot depend on upper layers.
|
||||
|
||||
---
|
||||
|
||||
### 3️⃣ Module Partitioning (Responsibility Boundaries)
|
||||
|
||||
For example, a trading system:
|
||||
|
||||
```text
|
||||
- market_data # Market data
|
||||
- strategy # Strategy
|
||||
- risk # Risk control
|
||||
- order # Order placement
|
||||
- account # Account
|
||||
```
|
||||
|
||||
👉 Each module:
|
||||
|
||||
* Does only one type of thing.
|
||||
* Aims for low coupling, high cohesion.
|
||||
|
||||
---
|
||||
|
||||
### 4️⃣ Data and Control Flow
|
||||
|
||||
* Where does the data come from?
|
||||
* Who is responsible for processing?
|
||||
* Who is responsible for storage?
|
||||
* Who is responsible for external output?
|
||||
|
||||
For example:
|
||||
|
||||
```text
|
||||
WebSocket → Data Cleaning → Indicator Calculation → AI Scoring → SQLite → API → Frontend
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 5️⃣ Technology Selection (Part of Architecture)
|
||||
|
||||
* Programming languages (Python / Java / Go)
|
||||
* Frameworks (FastAPI / Spring / Django)
|
||||
* Communication methods (HTTP / WebSocket / MQ)
|
||||
* Storage (SQLite / Redis / PostgreSQL)
|
||||
* Deployment (Local / Docker / Cloud)
|
||||
|
||||
---
|
||||
|
||||
## III. Common Project Architecture Types (Essential for Beginners)
|
||||
|
||||
### 1️⃣ Monolithic Architecture
|
||||
|
||||
```text
|
||||
One project, one process
|
||||
```
|
||||
|
||||
**Suitable for:**
|
||||
|
||||
* Personal projects
|
||||
* Prototypes
|
||||
* Small systems
|
||||
|
||||
**Advantages:**
|
||||
|
||||
* Simple
|
||||
* Easy to debug
|
||||
|
||||
**Disadvantages:**
|
||||
|
||||
* Difficult to scale later
|
||||
|
||||
---
|
||||
|
||||
### 2️⃣ Layered Architecture (Most Common)
|
||||
|
||||
```text
|
||||
Controller → Service → Repository
|
||||
```
|
||||
|
||||
**Suitable for:**
|
||||
|
||||
* Web backends
|
||||
* Business systems
|
||||
|
||||
---
|
||||
|
||||
### 3️⃣ Modular Architecture
|
||||
|
||||
```text
|
||||
core + plugins
|
||||
```
|
||||
|
||||
**Suitable for:**
|
||||
|
||||
* Pluggable systems
|
||||
* Strategy / indicator systems
|
||||
|
||||
👉 **Very suitable for quant, AI analysis you are doing.**
|
||||
|
||||
---
|
||||
|
||||
### 4️⃣ Microservice Architecture (Advanced)
|
||||
|
||||
```text
|
||||
Each service is an independent process + API communication
|
||||
```
|
||||
|
||||
**Suitable for:**
|
||||
|
||||
* Large teams
|
||||
* High concurrency
|
||||
* Long-term evolution
|
||||
|
||||
❌ **Not recommended for beginners to start with.**
|
||||
|
||||
---
|
||||
|
||||
## IV. Understanding with a "Real Example" (Close to what you are doing now)
|
||||
|
||||
Suppose you are building a **Binance Futures AI Analysis System**:
|
||||
|
||||
```text
|
||||
backend/
|
||||
├── data/
|
||||
│ └── binance_ws.py # Market data subscription
|
||||
├── indicators/
|
||||
│ └── vpvr.py
|
||||
├── strategy/
|
||||
│ └── signal_score.py
|
||||
├── storage/
|
||||
│ └── sqlite_writer.py
|
||||
├── api/
|
||||
│ └── http_server.py
|
||||
└── main.py
|
||||
```
|
||||
|
||||
This is **project architecture design**:
|
||||
|
||||
* Each folder is responsible for one thing.
|
||||
* Replaceable, testable.
|
||||
* Later, if you want to connect a Telegram Bot / Web frontend, you don't need to rewrite the core.
|
||||
|
||||
---
|
||||
|
||||
## V. Common Misconceptions for Beginners ⚠️
|
||||
|
||||
❌ Starting with microservices
|
||||
❌ All code in one file
|
||||
❌ Architecture pursuing "seniority" rather than "maintainability"
|
||||
❌ Starting to write code without clearly thinking about data flow
|
||||
|
||||
---
|
||||
|
||||
## VI. Suggested Learning Path (Very Important)
|
||||
|
||||
If you are learning CS now, this order is highly recommended:
|
||||
|
||||
1. **First write runnable projects (imperfect).**
|
||||
2. **Code becomes messy → then learn architecture.**
|
||||
3. Learn:
|
||||
|
||||
* Module decomposition
|
||||
* Layering
|
||||
* Dependency direction
|
||||
4. Then learn:
|
||||
|
||||
* Design patterns
|
||||
* Microservices / message queues
|
||||
|
||||
---
|
||||
|
||||
**Version**: 1.0
|
||||
**Update Date**: 2025-11-24
|
||||
**Maintained by**: CLAUDE, CODEX, KIMI
|
||||
@@ -1,5 +0,0 @@
|
||||
The texts that impressed me the most
|
||||
|
||||
Huangdi Yinfu Jing: Sever the benefit from one source, and use the master ten times. Three repetitions day and night, and use the master ten thousand times.
|
||||
|
||||
Douyin says: People are driven by profit; great profit leads to great deeds, small profit to small deeds, and no profit to no deeds.
|
||||
@@ -8,7 +8,6 @@ Core concepts and methodology for Vibe Coding.
|
||||
- [A Formalization of Recursive Self-Optimizing Generative Systems](./A%20Formalization%20of%20Recursive%20Self-Optimizing%20Generative%20Systems.md)
|
||||
- [System Prompt Construction Principles](./System%20Prompt%20Construction%20Principles.md)
|
||||
- [Development Experience](./Development%20Experience.md)
|
||||
- [Learning Experience](./Learning%20Experience.md)
|
||||
- [The Way of Programming](./The%20Way%20of%20Programming.md)
|
||||
- [Vibe Coding Experience Collection](./vibe-coding-experience-collection.md)
|
||||
- [Gemini Headless Mode Translation Guide](./Gemini%20Headless%20Mode%20Translation%20Guide.md)
|
||||
- [Code Organization](./Code%20Organization.md)
|
||||
- [General Project Architecture Template](./General%20Project%20Architecture%20Template.md)
|
||||
|
||||
@@ -1,59 +0,0 @@
|
||||
https://x.com/3i8ae3pgjz56244/status/1993328642697707736?s=46
|
||||
|
||||
I wrote the design document very detailed, including the specific logic of the service layer in pseudocode, and then handed it over to AI. It outputted the code in one go. Then I used another AI to review it, modified it according to the review comments, ran the test cases, and let the AI generate the commit and push.
|
||||
|
||||
Comment: Requirements -> Pseudocode -> Code
|
||||
|
||||
---
|
||||
|
||||
https://x.com/jesselaunz/status/1993231396035301437?s=20
|
||||
|
||||
For Gemini 3 Pro's system prompt, it improved the performance of multiple agent benchmarks by about 5%.
|
||||
|
||||
---
|
||||
|
||||
Point -> Line -> Body iterative refinement: for tasks within the scope of use, first polish a single basic task, then perform batch execution based on this.
|
||||
|
||||
---
|
||||
|
||||
https://x.com/nake13/status/1995123181057917032?s=46
|
||||
|
||||
---
|
||||
|
||||
https://x.com/9hills/status/1995308023578042844?s=46
|
||||
|
||||
---
|
||||
|
||||
File header comments, a paragraph describing the code's purpose, upstream and downstream links, documentation maintained by agents or Claude maintaining a paragraph description for each module, reducing cognitive load, trying to do subtraction and indexing, reference Claude skill.
|
||||
|
||||
---
|
||||
|
||||
https://x.com/dogejustdoit/status/1996464777313542204?s=46
|
||||
|
||||
As software scales, "looking at code" with human eyes not only fails to cope with increasing complexity but also exhausts developers. Code is ultimately converted into machine code for execution. High-level languages are just an abstraction to facilitate human understanding. What's important is to verify the program's execution logic and ensure correct behavior through automated testing, static analysis, formal verification, and other means. The core of future software engineering will not be "understanding code," but "verifying that code runs according to the correct logic."
|
||||
|
||||
---
|
||||
|
||||
https://x.com/yanboofficial/status/1996188311451480538?s=46
|
||||
|
||||
```prompt
|
||||
Based on my requirements, please create a real-time interactive 3D particle system using Three.js. If you do it well the first time, I will give you a $100 tip; my requirements are:
|
||||
```
|
||||
|
||||
Comment: This prompt may improve the generation effect.
|
||||
|
||||
---
|
||||
|
||||
https://x.com/zen_of_nemesis/status/1996591768641458368?s=46
|
||||
|
||||
---
|
||||
|
||||
https://github.com/tesserato/CodeWeaver
|
||||
|
||||
CodeWeaver weaves your codebase into a navigable Markdown document.
|
||||
|
||||
It can directly "weave" your entire project, no matter how much spaghetti code it has, into a clear and organized Markdown file with a tree-like structure, making it clear at a glance. All code is put into code blocks, greatly simplifying the sharing, documentation, and integration with AI/ML tools of the codebase.
|
||||
|
||||
---
|
||||
|
||||
https://x.com/magic47972451/status/1998639692905087356?s=46
|
||||
Reference in New Issue
Block a user