diff --git a/i18n/en/documents/00-fundamentals/Common Pitfalls.md b/i18n/en/documents/00-fundamentals/Common Pitfalls.md index e35bebb..0d4e7d8 100644 --- a/i18n/en/documents/00-fundamentals/Common Pitfalls.md +++ b/i18n/en/documents/00-fundamentals/Common Pitfalls.md @@ -1,3 +1,4 @@ +```markdown # 🕳️ Common Pitfalls Summary > Common issues and solutions during the Vibe Coding process @@ -5,18 +6,18 @@ ---
-🤖 AI Chat Related +🤖 AI Conversation Related -| Issue | Reason | Solution | +| Problem | Reason | Solution | |:---|:---|:---| -| AI generated code doesn't run | Insufficient context | Provide full error messages, describe the runtime environment | -| AI repeatedly modifies the same issue | Stuck in a loop | Describe with a different approach, or start a new conversation | -| AI hallucinating, fabricating non-existent APIs | Outdated model knowledge | Provide official documentation links for AI reference | -| Code becomes messy with changes | Lack of planning | Let AI propose a plan first, then write code after confirmation | -| AI doesn't understand my requirements | Vague description | Explain with concrete examples, provide input and output samples | -| AI forgets previous conversations | Context loss | Re-provide key information, or use a memory bank | -| AI modifies unintended code | Unclear instructions | Explicitly state "only modify xxx, do not touch other files" | -| AI generated code style is inconsistent | No style guide | Provide a code style guide or sample code | +| AI generated code doesn't run | Insufficient context | Provide full error message, explain execution environment | +| AI repeatedly modifies the same issue | Stuck in a loop | Try a different approach, or start a new conversation | +| AI hallucination, fabricating non-existent APIs | Outdated model knowledge | Provide official documentation link for AI reference | +| Code becomes messier after AI modifications | Lack of planning | Have AI propose a plan first, then confirm before coding | +| AI doesn't understand my requirements | Vague description | Use concrete examples, provide input/output samples | +| AI forgets previous conversation | Context loss | Re-provide key information, or use memory bank | +| AI modifies code it shouldn't have | Unclear instructions | Explicitly state "only modify xxx, don't touch other files" | +| AI generated code style is inconsistent | No style guide | Provide code style guide or example code |
@@ -31,7 +32,7 @@ - Keep the system Python clean - Easy to reproduce and deploy -### Creating and using .venv +### Create and use .venv ```bash # Create virtual environment @@ -50,15 +51,15 @@ pip install -r requirements.txt deactivate ``` -### Common Issues +### Common Problems -| Issue | Reason | Solution | +| Problem | Reason | Solution | |:---|:---|:---| -| Cannot configure environment at all | Global pollution | Delete and restart, use `.venv` for virtual environment isolation | +| Environment setup always fails | Global pollution | Delete and restart, isolate with `.venv` virtual environment | | `python` command not found | Virtual environment not activated | Run `source .venv/bin/activate` first | -| Package installed but import error | Installed globally | Confirm virtual environment is activated before `pip install` | -| Dependency conflicts in different projects | Sharing global environment | Create a separate `.venv` for each project | -| VS Code uses wrong Python | Interpreter not selected correctly | Ctrl+Shift+P → "Python: Select Interpreter" → Select .venv | +| Package installed but import error | Installed globally | Confirm virtual environment is active before `pip install` | +| Dependency conflicts between projects | Sharing global environment | Create a separate `.venv` for each project | +| VS Code uses wrong Python interpreter | Interpreter not selected correctly | Ctrl+Shift+P → "Python: Select Interpreter" → choose .venv | | pip version too old | Virtual environment defaults to old version | `pip install --upgrade pip` | | requirements.txt missing dependencies | Not exported | `pip freeze > requirements.txt` | @@ -83,15 +84,15 @@ pip install -r requirements.txt
📦 Node.js Environment Related -### Common Issues +### Common Problems -| Issue | Reason | Solution | +| Problem | Reason | Solution | |:---|:---|:---| | Node version mismatch | Project requires specific version | Use nvm to manage multiple versions: `nvm install 18` | -| `npm install` error | Network/Permission issues | Change registry, clear cache, delete `node_modules` and reinstall | +| `npm install` error | Network/Permissions issue | Change registry, clear cache, delete node_modules and reinstall | | Global package not found | PATH not configured | Add `npm config get prefix` to PATH | -| package-lock conflict | Collaborative work | Use `npm ci` instead of `npm install` consistently | -| `node_modules` too large | Normal phenomenon | Add to `.gitignore`, do not commit | +| package-lock conflict | Collaborative work | Consistently use `npm ci` instead of `npm install` | +| node_modules too large | Normal phenomenon | Add to .gitignore, do not commit | ### Common Commands @@ -106,7 +107,7 @@ npm cache clean --force rm -rf node_modules package-lock.json npm install -# Use nvm to switch Node version +# Switch Node version with nvm nvm use 18 ``` @@ -117,10 +118,10 @@ nvm use 18
🔧 Environment Configuration Related -| Issue | Reason | Solution | +| Problem | Reason | Solution | |:---|:---|:---| -| Command not found | Environment variables not configured | Check PATH, restart terminal | -| Port occupied | Not properly shut down last time | `lsof -i :port_number` or `netstat -ano \| findstr :port_number` | +| Command not found | Environment variable not configured | Check PATH, restart terminal | +| Port in use | Not properly closed last time | `lsof -i :port_number` or `netstat -ano \| findstr :port_number` | | Insufficient permissions | Linux/Mac permissions | `chmod +x` or `sudo` | | Environment variables not taking effect | Not sourced | `source ~/.bashrc` or restart terminal | | .env file not taking effect | Not loaded | Use `python-dotenv` or `dotenv` package | @@ -133,19 +134,19 @@ nvm use 18
🌐 Network Related -| Issue | Reason | Solution | +| Problem | Reason | Solution | |:---|:---|:---| | GitHub access slow/timeout | Network restrictions | Configure proxy, refer to [Network Environment Configuration](../从零开始vibecoding/01-网络环境配置.md) | | API call failed | Network/Key issue | Check proxy, API Key validity | | Terminal not using proxy | Incomplete proxy configuration | Set environment variables (see below) | | SSL certificate error | Proxy/Time issue | Check system time, or temporarily disable SSL verification | -| pip/npm download slow | Source is abroad | Change to domestic mirror source | +| pip/npm download slow | Source abroad | Use domestic mirror source | | git clone timeout | Network restrictions | Configure git proxy or use SSH | ### Terminal Proxy Configuration ```bash -# Temporary setting (effective in current terminal) +# Temporary setting (effective for current terminal) export http_proxy=http://127.0.0.1:7890 export https_proxy=http://127.0.0.1:7890 @@ -166,14 +167,14 @@ git config --global https.proxy http://127.0.0.1:7890
📝 Code Related -| Issue | Reason | Solution | +| Problem | Reason | Solution | |:---|:---|:---| | Code file too large, AI cannot process | Exceeds context | Split files, only provide relevant parts to AI | -| Code changes not taking effect | Cache/Not saved | Clear cache, confirm save, restart service | -| Merge conflicts | Git conflicts | Let AI help resolve: paste conflict content | -| Dependency version conflicts | Incompatible versions | Specify version numbers, or isolate with virtual environments | -| Chinese garbled characters | Encoding issue | Consistently use UTF-8, add `# -*- coding: utf-8 -*-` at file beginning | -| Hot update not taking effect | Watch issue | Check if file is within watch scope | +| Modified code not taking effect | Cache/Not saved | Clear cache, confirm save, restart service | +| Merge conflicts | Git conflict | Let AI help resolve: paste conflict content | +| Dependency version conflicts | Version incompatibility | Specify version number, or isolate with virtual environment | +| Chinese garbled characters | Encoding issue | Unify to UTF-8, add `# -*- coding: utf-8 -*-` at file beginning | +| Hot update not taking effect | Listening issue | Check if file is within listening range |
@@ -182,12 +183,12 @@ git config --global https.proxy http://127.0.0.1:7890
🎯 Claude Code / Cursor Related -| Issue | Reason | Solution | +| Problem | Reason | Solution | |:---|:---|:---| -| Claude Code cannot connect | Network/Authentication | Check proxy, re-run `claude login` | +| Claude Code cannot connect | Network/Authentication | Check proxy, re-`claude login` | | Cursor completion is slow | Network latency | Check proxy configuration | -| Quota exhausted | Limited free quota | Change account or upgrade to paid | -| Rules file not taking effect | Path/Format error | Check `.cursorrules` or `CLAUDE.md` location | +| Quota used up | Limited free quota | Switch accounts or upgrade to paid | +| Rule file not taking effect | Path/Format error | Check `.cursorrules` or `CLAUDE.md` location | | AI cannot read project files | Workspace issue | Confirm opened in correct directory, check .gitignore | | Generated code in wrong location | Cursor position | Place cursor at correct position before generating | @@ -198,11 +199,11 @@ git config --global https.proxy http://127.0.0.1:7890
🚀 Deployment Related -| Issue | Reason | Solution | +| Problem | Reason | Solution | |:---|:---|:---| -| Runs locally, fails on deployment | Environment differences | Check Node/Python versions, environment variables | +| Runs locally, but fails to deploy | Environment differences | Check Node/Python versions, environment variables | | Build timeout | Project too large | Optimize dependencies, increase build time limit | -| Environment variables not taking effect | Not configured | Set environment variables on the deployment platform | +| Environment variables not taking effect | Not configured | Set environment variables on deployment platform | | CORS cross-origin error | Backend not configured | Add CORS middleware | | Static files 404 | Path issue | Check build output directory configuration | | Insufficient memory | Free tier limitations | Optimize code or upgrade plan | @@ -214,12 +215,12 @@ git config --global https.proxy http://127.0.0.1:7890
🗄️ Database Related -| Issue | Reason | Solution | +| Problem | Reason | Solution | |:---|:---|:---| | Connection refused | Service not started | Start database service | -| Authentication failed | Incorrect password | Check username/password, reset password | +| Authentication failed | Incorrect password | Check username and password, reset password | | Table does not exist | Not migrated | Run migration | -| Data loss | Not persistent | Docker add volume, or use cloud database | +| Data loss | Not persisted | Docker with volume, or use cloud database | | Too many connections | Connections not closed | Use connection pool, close connections promptly |
@@ -229,7 +230,7 @@ git config --global https.proxy http://127.0.0.1:7890
🐳 Docker Related -| Issue | Reason | Solution | +| Problem | Reason | Solution | |:---|:---|:---| | Image pull failed | Network issue | Configure image accelerator | | Container failed to start | Port conflict/Configuration error | Check logs `docker logs container_name` | @@ -241,18 +242,18 @@ git config --global https.proxy http://127.0.0.1:7890 ---
-🧠 Large Model Usage Related +🧠 Large Language Model Usage Related -| Issue | Reason | Solution | +| Problem | Reason | Solution | |:---|:---|:---| -| Token limit exceeded | Input too long | Simplify context, only provide essential information | -| Response truncated | Output token limit | Ask AI to output in segments, or say "continue" | -| Large differences in model results | Different model characteristics | Select model based on task: Claude for code, GPT for general use | +| Token limit exceeded | Input too long | Refine context, only provide necessary information | +| Reply truncated | Output token limit | Ask AI to output in segments, or say "continue" | +| Significant differences in results between models | Different model characteristics | Choose model based on task: Claude for code, GPT for general purpose | | Temperature parameter effect | Temperature setting | Use low temperature (0-0.3) for code generation, high for creativity | | System prompt ignored | Prompt too long/conflicting | Simplify system prompt, put important parts first | -| JSON output format error | Model instability | Use JSON mode, or ask AI to only output code blocks | -| Multi-turn conversation quality degrades | Context pollution | Periodically start new conversations, keep context clean | -| API call error 429 | Rate limit | Add delay and retry, or upgrade API plan | +| JSON output format error | Model unstable | Use JSON mode, or ask AI to output only code blocks | +| Multi-turn conversation quality degrades | Context pollution | Regularly start new conversations, keep context clean | +| API call returns 429 error | Rate limit | Add delayed retries, or upgrade API plan | | Streaming output garbled | Encoding/Parsing issue | Check SSE parsing, ensure UTF-8 |
@@ -262,14 +263,14 @@ git config --global https.proxy http://127.0.0.1:7890
🏗️ Software Architecture Related -| Issue | Reason | Solution | +| Problem | Reason | Solution | |:---|:---|:---| -| Code becomes messy with changes | No architectural design | Draw architecture diagram first, then write code | -| Changing one place breaks many others | Tight coupling | Split modules, define clear interfaces | -| Don't know where to put code | Confused directory structure | Refer to [General Project Architecture Template](../模板与资源/通用项目架构模板.md) | -| Too much duplicate code | Lack of abstraction | Extract common functions/components | -| State management chaotic | Global state abuse | Use state management library, unidirectional data flow | -| Configuration scattered | No unified management | Centralize into config files or environment variables | +| Code becomes messier | No architectural design | Draw architecture diagram first, then write code | +| Changing one place breaks others | Too tightly coupled | Split modules, define clear interfaces | +| Don't know where to put code | Directory structure messy | Refer to [General Project Architecture Template](../模板与资源/通用项目架构模板.md) | +| Too much duplicate code | No abstraction | Extract common functions/components | +| State management chaotic | Overuse of global state | Use state management libraries, one-way data flow | +| Configuration scattered | No unified management | Centralize in config files or environment variables | | Difficult to test | Too many dependencies | Dependency injection, mock external services |
@@ -279,23 +280,23 @@ git config --global https.proxy http://127.0.0.1:7890
🔄 Git Version Control Related -| Issue | Reason | Solution | +| Problem | Reason | Solution | |:---|:---|:---| -| Committed unintended files | .gitignore not configured | Add to .gitignore, `git rm --cached` | +| Committed files that shouldn't be | .gitignore not configured | Add to .gitignore, `git rm --cached` | | Committed sensitive information | Not checked | Use git-filter-branch to clean history, change key | -| Cannot resolve merge conflicts | Unfamiliar with Git | Use VS Code conflict resolution tool, or ask AI for help | -| Commit message written incorrectly | Accidental | `git commit --amend` to modify | +| Don't know how to resolve merge conflicts | Unfamiliar with Git | Use VS Code conflict resolution tools, or ask AI for help | +| Committed with wrong message | Mistake | `git commit --amend` to modify | | Want to undo last commit | Committed wrongly | `git reset --soft HEAD~1` | -| Too many messy branches | No standardization | Use Git Flow or trunk-based | +| Too many messy branches | No standard | Use Git Flow or trunk-based | | Push rejected | New commits on remote | `pull --rebase` first, then push | ### Common Git Commands ```bash -# Undo changes in working directory +# Discard changes in working directory git checkout -- filename -# Undo changes in staging area +# Discard changes in staging area git reset HEAD filename # Undo last commit (keep changes) @@ -316,14 +317,14 @@ git stash pop
🧪 Testing Related -| Issue | Reason | Solution | +| Problem | Reason | Solution | |:---|:---|:---| -| Don't know what to test | Lack of testing mindset | Test edge cases, exceptions, core logic | +| Don't know what to test | Lack of testing mindset | Test edge cases, abnormal situations, core logic | | Tests are too slow | Test granularity too large | Write more unit tests, fewer E2E | -| Tests are unstable | Depends on external services | Mock external dependencies | -| Tests pass but bugs appear in production | Incomplete coverage | Add edge case tests, check with coverage | +| Tests are unstable | Dependent on external services | Mock external dependencies | +| Tests pass but bugs appear online | Incomplete coverage | Add edge case tests, check with coverage | | Changing code requires changing tests | Tests coupled to implementation | Test behavior, not implementation | -| AI generated tests are useless | Only tests happy path | Ask AI to supplement edge case and exception tests | +| AI generated tests are useless | Only tests happy path | Ask AI to supplement edge case and abnormal tests |
@@ -332,14 +333,14 @@ git stash pop
⚡ Performance Related -| Issue | Reason | Solution | +| Problem | Reason | Solution | |:---|:---|:---| -| Page loads slowly | Resources too large | Compression, lazy loading, CDN | -| API response slow | Queries not optimized | Add indexes, caching, pagination | +| Page loading slow | Resources too large | Compression, lazy loading, CDN | +| API response slow | Unoptimized queries | Add index, caching, pagination | | Memory leak | Resources not cleaned up | Check event listeners, timers, closures | -| High CPU usage | Infinite loop/Redundant computation | Use profiler to locate hotspots | -| Database queries slow | N+1 issue | Use JOIN or batch queries | -| Frontend lagging | Too many re-renders | React.memo, useMemo, virtualized lists | +| High CPU usage | Infinite loop/Repetitive calculation | Use profiler to locate hot spots | +| Slow database queries | N+1 problem | Use JOIN or batch queries | +| Frontend stuttering | Too many re-renders | React.memo, useMemo, virtual list |
@@ -348,14 +349,14 @@ git stash pop
🔐 Security Related -| Issue | Reason | Solution | +| Problem | Reason | Solution | |:---|:---|:---| | API Key leaked | Committed to Git | Use environment variables, add to .gitignore | -| SQL Injection | SQL concatenation | Use parameterized queries/ORM | -| XSS Attack | User input not escaped | Escape HTML, use CSP | -| CSRF Attack | No token verification | Add CSRF token | -| Password stored in plaintext | Lack of security awareness | Use bcrypt or other hashing algorithms | -| Sensitive information in logs | Printed unintended data | Anonymize, disable debug in production | +| SQL injection | String concatenation for SQL | Use parameterized queries/ORM | +| XSS attack | User input not escaped | Escape HTML, use CSP | +| CSRF attack | No token verification | Add CSRF token | +| Passwords stored in plaintext | Lack of security awareness | Use bcrypt or other hashing algorithms | +| Sensitive information in logs | Printed what shouldn't be | Anonymize data, disable debug in production |
@@ -364,15 +365,15 @@ git stash pop
📱 Frontend Development Related -| Issue | Reason | Solution | +| Problem | Reason | Solution | |:---|:---|:---| | Styles not taking effect | Priority/Cache | Check selector priority, clear cache | -| Mobile adaptation issues | Not responsive | Use rem/vw, media queries | +| Mobile adaptation issues | No responsive design | Use rem/vw, media queries | | White screen | JS error | Check console, add error boundaries | | State not synchronized | Asynchronous issues | Use useEffect dependencies, or state management library | | Component not updating | Reference not changed | Return new object/array, do not modify directly | -| Build size too large | Not optimized | On-demand import, code splitting, tree shaking | -| Cross-origin issues | Browser security policy | Backend configure CORS, or use proxy | +| Bundle size too large | No optimization | On-demand import, code splitting, tree shaking | +| Cross-origin issue | Browser security policy | Backend configure CORS, or use proxy |
@@ -381,14 +382,14 @@ git stash pop
🖥️ Backend Development Related -| Issue | Reason | Solution | +| Problem | Reason | Solution | |:---|:---|:---| -| API returns slowly | Synchronous blocking | Use async, put time-consuming tasks in queue | +| API response slow | Synchronous blocking | Use asynchronous, put time-consuming tasks in queue | | Concurrency issues | Race conditions | Add locks, use transactions, optimistic locking | -| Service crashed undetected | No monitoring | Add health checks, alerts | -| Logs cannot find issues | Incomplete logs | Add request_id, structured logging | -| Configure different environments | Hardcoding | Use environment variables to distinguish dev/prod | -| OOM crash | Memory leak/Too much data | Pagination, streaming, check for leaks | +| Service crashed without detection | No monitoring | Add health checks, alerts | +| Logs not helping to find issues | Incomplete logs | Add request_id, structured logging | +| Different environment configuration | Hardcoding | Use environment variables to distinguish dev/prod | +| OOM crashes | Memory leak/Too much data | Paging, streaming, check for leaks |
@@ -397,12 +398,12 @@ git stash pop
🔌 API Design Related -| Issue | Reason | Solution | +| Problem | Reason | Solution | |:---|:---|:---| -| API naming chaotic | No standardization | Follow RESTful, use HTTP verbs for actions | +| API naming chaotic | No standard | Follow RESTful, use HTTP methods as verbs | | Return format inconsistent | No agreement | Unify response structure `{code, data, message}` | | Version upgrade difficult | No version control | Add version number to URL `/api/v1/` | -| Documentation and implementation inconsistent | Manual maintenance | Use Swagger/OpenAPI for auto-generation | +| Documentation and implementation inconsistent | Manual maintenance | Use Swagger/OpenAPI to auto-generate | | Error messages unclear | Only returns 500 | Refine error codes, return useful information | | Pagination parameters inconsistent | Each written differently | Unify `page/size` or `offset/limit` | @@ -413,13 +414,13 @@ git stash pop
📊 Data Processing Related -| Issue | Reason | Solution | +| Problem | Reason | Solution | |:---|:---|:---| -| Data format incorrect | Type conversion issues | Perform type validation and conversion | -| Timezone issues | Timezones not unified | Store UTC, convert to local time for display | -| Precision loss | Floating point issues | Use integers (cents) for monetary values, or Decimal | +| Data format incorrect | Type conversion issue | Perform type validation and conversion properly | +| Timezone issues | Timezones not unified | Store in UTC, convert to local for display | +| Precision loss | Floating-point issues | Use integers for currency (cents), or Decimal | | Large file processing OOM | Loaded all at once | Stream processing, chunked reading | -| Encoding issues | Not UTF-8 | Consistently use UTF-8, specify encoding when reading files | +| Encoding issues | Not UTF-8 | Unify to UTF-8, specify encoding when reading files | | Null value handling | null/undefined | Perform null checks, provide default values |
@@ -429,22 +430,22 @@ git stash pop
🤝 Collaboration Related -| Issue | Reason | Solution | +| Problem | Reason | Solution | |:---|:---|:---| -| Code style inconsistent | No standardization | Use ESLint/Prettier/Black, unify configuration | -| PR too large, difficult to review | Too many changes | Commit in small steps, one PR per feature | -| Documentation outdated | No one maintains | Update code and documentation together, CI checks | +| Code style inconsistent | No standard | Use ESLint/Prettier/Black, unify configuration | +| PR too large, difficult to review | Too many changes | Small, incremental commits, one PR per feature | +| Documentation outdated | No one maintains | Update code and documentation together, CI check | | Don't know who is responsible | No owner | Use CODEOWNERS file | | Reinventing the wheel | Unaware of existing solutions | Establish internal component library/documentation |
-1. **Check error messages** - Copy the full error to AI -2. **Minimum reproduction** - Find the simplest code that reproduces the issue -3. **Bisection method** - Comment out half the code to narrow down the problem scope -4. **Change environment** - Try different browsers/terminals/devices +1. **Check error message** - Copy it completely to AI +2. **Minimal reproduction** - Find the simplest code that reproduces the issue +3. **Bisection method** - Comment out half of the code, pinpoint the problem area +4. **Change environment** - Try a different browser/terminal/device 5. **Restart magic** - Restart service/editor/computer -6. **Delete and restart** - If the environment is messed up, delete and recreate the virtual environment +6. **Delete and restart** - If the environment is messy, delete and recreate the virtual environment --- @@ -453,25 +454,26 @@ git stash pop Still can't figure it out? Try this prompt: ``` -I've encountered an issue and have tried many methods without success. +I encountered a problem and have tried many methods without success. Error message: [Paste full error] My environment: -- Operating system: -- Python/Node version: +- Operating System: +- Python/Node Version: - Relevant dependency versions: -I have tried: +I have already tried: 1. xxx 2. xxx -Please help me analyze the possible causes and provide solutions. +Please help me analyze possible causes and provide solutions. ``` --- ## 📝 Contribution -Found a new pitfall? Welcome PR contributions! +Found a new pitfall? Welcome to PR to supplement! +``` diff --git a/i18n/en/documents/00-fundamentals/General Project Architecture Template.md b/i18n/en/documents/00-fundamentals/General Project Architecture Template.md index 5f8937d..6e9995c 100644 --- a/i18n/en/documents/00-fundamentals/General Project Architecture Template.md +++ b/i18n/en/documents/00-fundamentals/General Project Architecture Template.md @@ -1,11 +1,12 @@ -# General Project Architecture Template +``` +# Generic Project Architecture Template ## 1️⃣ Standard Structure for Python Web/API Projects ``` -project_name/ -├── README.md # Project README -├── LICENSE # Open-source license +项目名称/ +├── README.md # Project description document +├── 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) @@ -14,7 +15,7 @@ project_name/ ├── .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 ^_^ +├── Sublime-Text.txt # For requirements and notes, for myself, and CLI session recovery commands ^_^ │ ├── docs/ # Documentation directory │ ├── api.md # API documentation @@ -33,7 +34,7 @@ project_name/ │ ├── integration/ # Integration tests │ └── test_config.py # Configuration tests │ -├── src/ # Source code (recommended) +├── src/ # Source code (recommended approach) │ ├── __init__.py │ ├── main.py # Program entry point │ ├── app.py # Flask/FastAPI application @@ -58,7 +59,7 @@ project_name/ │ └── external/ # External services │ ├── __init__.py │ ├── clients/ # API clients -│ └── integrations/ # Integration services +│ └── integrations/ # Integrated services │ ├── logs/ # Log directory (not committed to Git) │ ├── app.log @@ -70,14 +71,14 @@ project_name/ └── cache/ # Cache ``` -**Use Cases**: Flask/FastAPI Web applications, RESTful API services, Web backends +**Usage Scenarios**: Flask/FastAPI Web applications, RESTful API services, Web backends --- ## 2️⃣ Standard Structure for Data Science/Quant Projects ``` -project_name/ +项目名称/ ├── README.md ├── LICENSE ├── requirements.txt @@ -86,7 +87,7 @@ project_name/ ├── .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 ^_^ +├── Sublime-Text.txt # For requirements and notes, for myself, and CLI session recovery commands ^_^ │ ├── docs/ # Documentation directory │ ├── notebooks/ # Jupyter documentation @@ -99,7 +100,7 @@ project_name/ │ ├── scripts/ # Script tools │ ├── train_model.py # Training script -│ ├── backtest.py # Backtest script +│ ├── backtest.py # Backtesting script │ ├── collect_data.py # Data collection │ └── deploy_model.py # Model deployment │ @@ -125,12 +126,12 @@ project_name/ │ ├── models/ # Model module │ │ ├── __init__.py │ │ ├── strategies/ # Trading strategies -│ │ ├── backtest/ # Backtest engine +│ │ ├── backtest/ # Backtesting engine │ │ └── risk/ # Risk management │ │ │ ├── utils/ # Utility module │ │ ├── __init__.py -│ │ ├── logging.py # Log configuration +│ │ ├── logging.py # Logging configuration │ │ ├── database.py # Database tools │ │ └── api_client.py # API client │ │ @@ -138,7 +139,7 @@ project_name/ │ ├── __init__.py │ ├── config.py # Configuration management │ ├── signals.py # Signal generation -│ └── portfolio.py # Portfolio +│ └── portfolio.py # Investment portfolio │ ├── data/ # Data directory (Git ignored) │ ├── raw/ # Raw data @@ -155,14 +156,14 @@ project_name/ └── errors.log ``` -**Use Cases**: Quantitative trading, machine learning, data analysis, AI research +**Usage Scenarios**: Quantitative trading, machine learning, data analysis, AI research --- -## 3️⃣ Monorepo (Multi-Project Repository) Standard Structure +## 3️⃣ Standard Structure for Monorepo (Multi-Project Repository) ``` -project_name-monorepo/ +项目名称-monorepo/ ├── README.md ├── LICENSE ├── .gitignore @@ -170,7 +171,7 @@ project_name-monorepo/ ├── 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 ^_^ +├── Sublime-Text.txt # This is a file for requirements and notes, for myself, and CLI session recovery commands ^_^ │ ├── docs/ # Global documentation │ ├── architecture.md @@ -183,9 +184,9 @@ project_name-monorepo/ │ ├── backups/ # Backup files │ ├── archive/ # Old backup files -│ └── gz/ # Gzip backup files +│ └── gz/ # Compressed backup files │ -├── services/ # Microservice directory +├── services/ # Microservices directory │ │ │ ├── user-service/ # User service │ │ ├── Dockerfile @@ -209,35 +210,35 @@ project_name-monorepo/ │ ├── common/ # Common modules │ │ ├── utils/ │ │ └── models/ -│ ├── external/ # Third-party libraries (immutable, call only) +│ ├── external/ # Third-party libraries (not modifiable, only callable) │ └── database/ # Database access library │ ├── infrastructure/ # Infrastructure -│ ├── terraform/ # Cloud resource definition +│ ├── terraform/ # Cloud resource definitions │ ├── kubernetes/ # K8s configuration │ └── nginx/ # Reverse proxy configuration │ └── monitoring/ # Monitoring system - ├── prometheus/ # Metrics collection + ├── prometheus/ # Metric collection ├── grafana/ # Visualization - └── alertmanager/ # Alerts + └── alertmanager/ # Alerting ``` -**Use Cases**: Microservice architecture, large projects, team collaboration +**Usage Scenarios**: Microservices architecture, large-scale projects, team collaboration --- ## 4️⃣ Standard Structure for Full-Stack Web Applications ``` -project_name/ +项目名称/ ├── README.md ├── LICENSE ├── .gitignore -├── docker-compose.yml # Frontend and backend orchestration +├── docker-compose.yml # Frontend and backend orchestration together ├── 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 ^_^ +├── Sublime-Text.txt # For requirements and notes, for myself, and CLI session recovery commands ^_^ │ ├── frontend/ # Frontend directory │ ├── public/ # Static assets @@ -259,7 +260,7 @@ project_name/ └── tests/ ``` -**Use Cases**: Full-stack applications, SPA single-page applications, frontend/backend separated projects +**Usage Scenarios**: Full-stack applications, SPA single-page applications, frontend/backend separation projects --- @@ -268,12 +269,12 @@ project_name/ ### 1. Separation of Concerns ``` API → Service → Data Access → Database -Clear at a glance, clear hierarchy +Clear, hierarchical, and easy to understand ``` ### 2. Testability ``` -Each module is independently testable +Each module can be tested independently Dependencies can be mocked ``` @@ -285,12 +286,12 @@ Environment variables > Configuration files > Default values ### 4. Maintainability ``` -Self-documenting code +Self-explanatory code Reasonable file naming Clear directory structure ``` -### 5. Version Control Friendly (Git-Friendly) +### 5. Git-Friendly ``` data/, logs/, models/ added to .gitignore Only commit source code and configuration examples @@ -300,16 +301,16 @@ 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. +1. **Use the `src/` directory**: Place source code in a dedicated `src` directory to avoid cluttering the top-level directory. +2. **Relative imports**: Consistently use import statements like `from src.module import thing`. 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. +4. **Documentation first**: Write `README.md` for important modules. +5. **Environment isolation**: Use virtualenv or conda to create independent environments. +6. **Explicit dependencies**: All dependencies should be listed in `requirements.txt` with locked versions. +7. **Configuration management**: Use a combination of environment variables and 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. +9. **Error handling**: Do not suppress exceptions; ensure a complete error chain. +10. **Code style**: Use black for formatting and flake8 for linting. --- @@ -366,10 +367,10 @@ temp/ --- -## 📚 Technology Selection Reference +## 📚 Technology Stack Reference -| Scenario | Recommended Tech Stack | -| :------- | :--------------------- | +| Scenario | Recommended Technology Stack | +|----------|-----------------------------| | Web API | FastAPI + Pydantic + SQLAlchemy | | Data Processing | Pandas + NumPy + Polars | | Machine Learning | Scikit-learn + XGBoost + LightGBM | @@ -387,7 +388,7 @@ temp/ ### requirements.txt ```txt -# Core dependencies +# Core Dependencies fastapi==0.104.1 uvicorn[standard]==0.24.0 pydantic==2.5.0 @@ -415,10 +416,10 @@ mypy==1.7.1 ### pyproject.toml (Recommended for modern Python projects) ```toml [project] -name = "Project Name" +name = "项目名称" version = "0.1.0" -description = "Project Description" -authors = [{name = "Author", email = "email@example.com"}] +description = "项目描述" +authors = [{name = "作者", email = "邮箱 @example.com"}] dependencies = [ "fastapi>=0.104.0", "uvicorn[standard]>=0.24.0", @@ -439,51 +440,51 @@ build-backend = "setuptools.build_meta" 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. +- [ ] Create `README.md`, including project introduction and usage instructions. +- [ ] Create `LICENSE` file, clarifying the open-source license. +- [ ] Set up a 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 the directory structure, adhering to the principle of separation of concerns. +- [ ] Create basic configuration files. +- [ ] Set up a code formatter (black). +- [ ] Set up a code linter (flake8/ruff). +- [ ] Write the first test case. +- [ ] Set up a Git repository and commit initial code. +- [ ] Create `CHANGELOG.md` to record version changes. --- -In **programming / software development**, **Project Architecture / Software Architecture** refers to: +In **programming / software development**, **project architecture (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. +> **A design plan 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 +## One-sentence understanding -**Project Architecture = Deciding "where the code goes, how modules connect, and how responsibilities are divided" before writing any specific business code.** +**Project Architecture = Before writing specific business code, first decide "where the code goes, how modules connect, and how responsibilities are divided."** --- -## I. What Problems Does Project Architecture Primarily Solve? +## I. What problems does project architecture mainly solve? -Project architecture is not about "coding skills," but about solving these **higher-level problems**: +Project architecture is not about "coding tricks," but about solving these **higher-level problems**: -* 📦 How to organize code to avoid chaos? -* 🔁 How do modules communicate? +* 📦 How to organize code so it doesn't get messy? +* 🔁 How do modules communicate with each other? * 🧱 Which parts can be modified independently without affecting the whole? -* 🚀 How will the project be extended in the future? +* 🚀 How will the project expand in the future? * 🧪 How to facilitate testing, debugging, and deployment? -* 👥 How to collaborate without stepping on each other's code? +* 👥 How can multiple people collaborate without stepping on each other's code? --- -## II. What Does Project Architecture Generally Include? +## II. What does project architecture generally include? -### 1️⃣ Directory Structure (Most Intuitive) +### 1️⃣ Directory Structure (Most intuitive) ```text project/ @@ -498,7 +499,7 @@ project/ └── README.md ``` -👉 Determines **"where different types of code are placed"**. +👉 Determines **"where different types of code are placed"** --- @@ -518,8 +519,8 @@ Database / External Systems **Rules:** -* Upper layers can call lower layers. -* Lower layers cannot depend on upper layers. +* Upper layers can call lower layers +* Lower layers cannot depend on upper layers in reverse --- @@ -537,8 +538,8 @@ For example, a trading system: 👉 Each module: -* Does only one type of thing. -* Aims for low coupling, high cohesion. +* Does only one type of thing +* Strives for low coupling, high cohesion --- @@ -547,7 +548,7 @@ For example, a trading system: * Where does the data come from? * Who is responsible for processing? * Who is responsible for storage? -* Who is responsible for external output? +* Who is responsible for output? For example: @@ -557,17 +558,17 @@ WebSocket → Data Cleaning → Indicator Calculation → AI Scoring → SQLite --- -### 5️⃣ Technology Selection (Part of Architecture) +### 5️⃣ Technology Stack Selection (Part of architecture) -* Programming languages (Python / Java / Go) -* Frameworks (FastAPI / Spring / Django) -* Communication methods (HTTP / WebSocket / MQ) +* Programming language (Python / Java / Go) +* Framework (FastAPI / Spring / Django) +* Communication method (HTTP / WebSocket / MQ) * Storage (SQLite / Redis / PostgreSQL) * Deployment (Local / Docker / Cloud) --- -## III. Common Project Architecture Types (Essential for Beginners) +## III. Common Project Architecture Types (Beginner must-know) ### 1️⃣ Monolithic Architecture @@ -592,7 +593,7 @@ One project, one process --- -### 2️⃣ Layered Architecture (Most Common) +### 2️⃣ Layered Architecture (Most common) ```text Controller → Service → Repository @@ -616,11 +617,11 @@ core + plugins * Pluggable systems * Strategy / indicator systems -👉 **Very suitable for quant, AI analysis you are doing.** +👉 **Very suitable for quant and AI analysis that you are doing** --- -### 4️⃣ Microservice Architecture (Advanced) +### 4️⃣ Microservices Architecture (Advanced) ```text Each service is an independent process + API communication @@ -632,13 +633,13 @@ Each service is an independent process + API communication * High concurrency * Long-term evolution -❌ **Not recommended for beginners to start with.** +❌ **Not recommended for beginners to start with** --- -## IV. Understanding with a "Real Example" (Close to what you are doing now) +## IV. Understand with a "Real Example" (Closer to what you are doing) -Suppose you are building a **Binance Futures AI Analysis System**: +Suppose you are building an **AI analysis system for Binance perpetual contracts**: ```text backend/ @@ -657,39 +658,38 @@ backend/ 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. +* Each folder is responsible for one thing +* Replaceable, testable +* No need to rewrite core logic if you want to integrate Telegram Bot / Web frontend later --- -## V. Common Misconceptions for Beginners ⚠️ +## V. Common Mistakes 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 +❌ All code written in one file +❌ Pursuing "advanced" architecture instead of "maintainable" architecture +❌ Writing code without a clear understanding of data flow --- -## VI. Suggested Learning Path (Very Important) +## VI. Learning Path Recommendations (Very Important) -If you are learning CS now, this order is highly recommended: +Since you are studying CS, this order is highly recommended: -1. **First write runnable projects (imperfect).** -2. **Code becomes messy → then learn architecture.** +1. **First build a runnable project (not perfect)** +2. **When code starts getting messy → then learn architecture** 3. Learn: - - * Module decomposition + * Module partitioning * Layering * Dependency direction 4. Then learn: - * Design patterns - * Microservices / message queues + * Microservices / Message queues --- **Version**: 1.0 **Update Date**: 2025-11-24 -**Maintained by**: CLAUDE, CODEX, KIMI +**Maintainers**: CLAUDE, CODEX, KIMI +``` diff --git a/i18n/en/documents/00-fundamentals/Glue Coding.md b/i18n/en/documents/00-fundamentals/Glue Coding.md index dbc3a4d..9fae4fb 100644 --- a/i18n/en/documents/00-fundamentals/Glue Coding.md +++ b/i18n/en/documents/00-fundamentals/Glue Coding.md @@ -1,6 +1,6 @@ # 🧬 Glue Coding -> **The holy grail and silver bullet of software engineering – it's finally here.** +> **The holy grail and silver bullet of software engineering - finally here.** --- @@ -10,11 +10,11 @@ It might perfectly solve the three fatal flaws of Vibe Coding: -| Pain Points of Traditional Vibe Coding | Glue Coding's Solution | +| Traditional Vibe Coding Pain Points | Glue Coding Solution | |:---|:---| -| 🎭 **AI Hallucinations** - Generating non-existent APIs, incorrect logic | ✅ **Zero Hallucinations** - Only using validated, mature code | -| 🧩 **Complexity Explosion** - The larger the project, the more out of control it becomes | ✅ **Zero Complexity** - Every module is a time-tested wheel | -| 🎓 **High Barrier to Entry** - Requires deep programming skills to master AI | ✅ **Barrier Disappears** - You only need to describe "how to connect" | +| 🎭 **AI Hallucinations** - Generates non-existent APIs, incorrect logic | ✅ **Zero Hallucinations** - Uses only validated, mature code | +| 🧩 **Complexity Explosion** - The larger the project, the more out of control | ✅ **Zero Complexity** - Each module is a battle-tested wheel | +| 🎓 **High Barrier** - Requires deep programming skills to master AI | ✅ **No Barrier** - You only need to describe "how to connect" | --- @@ -30,13 +30,13 @@ Glue Coding: AI connects code, humans review connections **A fundamental shift from "generation" to "connection":** -- ❌ No longer letting AI generate code from scratch (the source of hallucinations) -- ❌ No longer reinventing the wheel (the source of complexity) -- ❌ No longer requiring you to understand every line of code (the source of high barriers) +- ❌ No longer letting AI generate code from scratch (source of hallucinations) +- ❌ No longer reinventing the wheel (source of complexity) +- ❌ No longer requiring you to understand every line of code (source of high barrier) - ✅ Only reusing mature, production-validated open-source projects -- ✅ AI's sole responsibility: understanding your intent and connecting modules -- ✅ Your sole responsibility: clearly describing "what is the input, what is the desired output" +- ✅ AI's sole responsibility: understand your intent, connect modules +- ✅ Your sole responsibility: clearly describe "what is the input, what is the desired output" --- @@ -44,7 +44,7 @@ Glue Coding: AI connects code, humans review connections ``` ┌─────────────────────────────────────────────────────────┐ -│ Your Business Needs │ +│ Your Business Needs │ └─────────────────────────────────────────────────────────┘ │ ▼ @@ -59,71 +59,71 @@ Glue Coding: AI connects code, humans review connections ▼ ▼ ▼ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ Mature Module A │ │ Mature Module B │ │ Mature Module C │ - │ (100K+ ⭐) │ │ (Production Validated) │ │ (Official SDK) │ + │ (100K+ ⭐) │ │ (Production-Validated) │ │ (Official SDK) │ └─────────────┘ └─────────────┘ └─────────────┘ ``` -**Entity**: Mature open-source projects, official SDKs, time-tested libraries +**Entity**: Mature open-source projects, official SDKs, battle-tested libraries **Link**: AI-generated glue code, responsible for data flow and interface adaptation -**Function**: Your described business objective +**Function**: Your described business goal --- -## 🎯 Why is this the Silver Bullet? +## 🎯 Why is this a Silver Bullet? -### 1. Hallucination Problem → Completely Disappears +### 1. Hallucination Issue → Completely Disappears AI no longer needs to "invent" anything. It only needs to: - Read Module A's documentation - Read Module B's documentation -- Write the data transformation from A to B +- Write the data transformation from A → B **This is what AI excels at, and what is least prone to errors.** -### 2. Complexity Problem → Transferred to the Community +### 2. Complexity Issue → Transferred to the Community Behind each module are: -- Thousands of Issue discussions -- Hundreds of contributors' wisdom +- Discussions from thousands of Issues +- Wisdom from hundreds of contributors - Years of production environment refinement -**You are not managing complexity, you are standing on the shoulders of giants.** +**You are not managing complexity; you are standing on the shoulders of giants.** -### 3. Barrier to Entry Problem → Reduced to a Minimum +### 3. Barrier Issue → Reduced to a Minimum You don't need to understand: - Underlying implementation principles - Best practice details - Edge case handling -You just need to speak human language: -> "I want to process Telegram messages with GPT and save them to PostgreSQL" +You only need to speak plain language: +> "I want to take messages from Telegram, process them with GPT, and store them in PostgreSQL" -**AI will help you find the most suitable wheels and then glue them together.** +**AI will help you find the most suitable wheels and glue them together.** --- -## 📋 Practical Workflow +## 📋 Practice Flow ``` -1. Clarify Goal - └─→ "I want to implement XXX function" +1. Define the Goal + └─→ "I want to implement XXX functionality" -2. Find Wheels +2. Find the Wheels └─→ "Are there any mature libraries/projects that have done something similar?" └─→ Let AI help you search, evaluate, and recommend -3. Understand Interfaces +3. Understand the Interfaces └─→ Feed the official documentation to AI └─→ AI summarizes: what is the input, what is the output -4. Describe Connection +4. Describe the Connection └─→ "The output of A should become the input of B" └─→ AI generates glue code -5. Verify Run +5. Validate and Run └─→ Runs successfully → Done - └─→ Error → Give the error to AI, continue gluing + └─→ Errors → Give the errors to AI, continue gluing ``` --- @@ -132,9 +132,9 @@ You just need to speak human language: ### Case: Polymarket Data Analysis Bot -**Requirement**: Real-time acquisition of Polymarket data, analysis, and pushing to Telegram +**Requirement**: Real-time acquisition of Polymarket data, analysis, and push to Telegram -**Traditional Approach**: Write a crawler from scratch, write analysis logic, write a Bot → 3000 lines of code, 2 weeks +**Traditional Approach**: Write a crawler, analysis logic, and bot from scratch → 3000 lines of code, 2 weeks **Glue Approach**: ``` @@ -150,21 +150,21 @@ Development Time: 2 hours ## 📚 Further Reading -- [语言层要素](./语言层要素.md) - 8 Levels of Understanding 100% Code -- [胶水开发提示词](../../prompts/coding_prompts/胶水开发.md) -- [项目实战：polymarket-dev](../项目实战经验/polymarket-dev/) +- [Language Layer Elements](./语言层要素.md) - 8 levels to master to understand 100% of the code +- [Glue Development Prompts](../../prompts/coding_prompts/胶水开发.md) +- [Project Practice: polymarket-dev](../项目实战经验/polymarket-dev/) --- ## 🎖️ Summary -> **If you can copy, don't write; if you can connect, don't build; if you can reuse, don't originate.** +> **If you can copy, don't write. If you can connect, don't build. If you can reuse, don't originate.** Glue Coding is the ultimate evolution of Vibe Coding. -It's not laziness, but **the highest manifestation of engineering wisdom** – +It's not laziness; it's the **highest embodiment of engineering wisdom** — -Using the least amount of original code to leverage the greatest productivity. +Leveraging maximum productivity with minimal original code. **This is the silver bullet software engineering has been waiting for for 50 years.** @@ -176,11 +176,11 @@ Using the least amount of original code to leverage the greatest productivity. ## **1. Definition of Glue Coding** -**Glue coding** is a new software construction method, whose core idea is: +**Glue Coding** is a new software construction approach, with its core philosophy being: -> **Almost entirely reusing mature open-source components, combining them into a complete system with a minimal amount of "glue code".** +> **Almost entirely reusing mature open-source components, combining them into a complete system with minimal "glue code"** -It emphasizes "connection" rather than "creation", especially efficient in the AI era. +It emphasizes "connecting" rather than "creating," and is especially efficient in the AI era. ## **2. Background** @@ -189,54 +189,54 @@ Traditional software engineering often requires developers to: * Design architecture * Write logic themselves * Manually handle various details -* Reinvent the wheel +* Reinvent the wheel repeatedly This leads to high development costs, long cycles, and low success rates. However, the current ecosystem has fundamentally changed: -* Thousands of mature open-source libraries on GitHub -* Frameworks covering various scenarios (Web, AI, Distributed, Model Inference...) +* There are countless mature open-source libraries on GitHub +* Frameworks cover various scenarios (Web, AI, distributed, model inference…) * GPT / Grok can help search, analyze, and combine these projects In this environment, writing code from scratch is no longer the most efficient way. -Thus, "glue coding" has emerged as a new paradigm. +Thus, "Glue Coding" has emerged as a new paradigm. ## **3. Core Principles of Glue Coding** ### **3.1 Don't write what can be avoided, write as little as possible** -Any functionality with a mature existing implementation should not be reinvented. +Any functionality with an existing mature implementation should not be reinvented. ### **3.2 Copy-paste whenever possible** Directly copying and using community-validated code is a normal engineering process, not laziness. -### **3.3 Stand on the shoulders of giants, don't try to be a giant** +### **3.3 Stand on the shoulders of giants, rather than trying to become one** Utilize existing frameworks instead of trying to write a "better wheel" yourself. -### **3.4 Do not modify original repository code** +### **3.4 Do not modify the original repository code** -All open-source libraries should ideally remain immutable, used as black boxes. +All open-source libraries should ideally remain immutable and be used as black boxes. -### **3.5 The less custom code, the better** +### **3.5 Minimize custom code** -Your written code only serves to: +The code you write should only be responsible for: -* Combine -* Call -* Encapsulate -* Adapt +* Combination +* Invocation +* Encapsulation +* Adaptation -Which is the so-called **glue layer**. +This is what is called the **glue layer**. -## **4. Standard Workflow of Glue Coding** +## **4. Standard Process of Glue Coding** ### **4.1 Clarify Requirements** -Break down the system's functionality into individual requirements. +Break down the system's desired functionalities into individual requirements. ### **4.2 Use GPT/Grok to Deconstruct Requirements** @@ -244,20 +244,20 @@ Let AI refine requirements into reusable modules, capabilities, and correspondin ### **4.3 Search for Existing Open-Source Implementations** -Leverage GPT's internet capabilities (e.g., Grok): +Utilize GPT's web browsing capabilities (e.g., Grok): -* Search for corresponding GitHub repositories for each sub-requirement. -* Check for reusable components. +* Search for corresponding GitHub repositories for each sub-requirement +* Check for existing reusable components * Compare quality, implementation methods, licenses, etc. -#### 🔍 Using GitHub Topics to Find the Right Wheels +#### 🔍 Use GitHub Topics to Precisely Find Wheels -**Method**: Ask AI to find the GitHub Topic for your requirement, then browse popular repos under that topic. +**Method**: Let AI help you find GitHub Topics corresponding to your needs, then browse popular repositories under that topic. **Example Prompt**: ``` -I need to implement [your requirement], please help me: -1. Analyze what technical areas this requirement might involve +I need to implement [Your Requirement]. Please help me: +1. Analyze which technical fields this requirement might involve 2. Recommend corresponding GitHub Topics keywords 3. Provide GitHub Topics links (format: https://github.com/topics/xxx) ``` @@ -269,20 +269,20 @@ I need to implement [your requirement], please help me: | Data Analysis | [data-analysis](https://github.com/topics/data-analysis) | | AI Agent | [ai-agent](https://github.com/topics/ai-agent) | | CLI Tool | [cli](https://github.com/topics/cli) | -| Web Scraping | [web-scraping](https://github.com/topics/web-scraping) | +| Web Scraper | [web-scraping](https://github.com/topics/web-scraping) | **Advanced Tips**: - [GitHub Topics Homepage](https://github.com/topics) - Browse all topics -- [GitHub Trending](https://github.com/trending) - Discover hot new projects -- Combine multiple Topics: `https://github.com/topics/python?q=telegram` +- [GitHub Trending](https://github.com/trending) - Discover popular new projects +- Combine multiple Topic filters: `https://github.com/topics/python?q=telegram` ### **4.4 Download and Organize Repositories** Pull the selected repositories locally and organize them by category. -### **4.5 Organize According to Architectural System** +### **4.5 Organize by Architectural System** -Place these repositories into the project structure, for example: +Place these repositories within the project structure, for example: ``` /services @@ -291,14 +291,14 @@ Place these repositories into the project structure, for example: /glue ``` -And emphasize: **Open-source repositories are third-party dependencies and must never be modified.** +And emphasize: **Open-source repositories, as third-party dependencies, must absolutely not be modified.** ### **4.6 Write Glue Layer Code** The role of glue code includes: * Encapsulating interfaces -* Unifying input/output +* Unifying input and output * Connecting different components * Implementing minimal business logic @@ -308,7 +308,7 @@ The final system is composed of multiple mature modules. ### **5.1 Extremely High Success Rate** -Because it uses community-validated mature code. +Because it uses community-validated, mature code. ### **5.2 Extremely Fast Development Speed** @@ -316,9 +316,9 @@ A large amount of functionality can be directly reused. ### **5.3 Reduced Costs** -Time cost, maintenance cost, and learning cost are all significantly reduced. +Time costs, maintenance costs, and learning costs are significantly reduced. -### **5.4 More Stable System** +### **5.4 More Stable Systems** Relies on mature frameworks rather than individual implementations. @@ -332,31 +332,31 @@ GPT can assist in searching, deconstructing, and integrating, making it a natura ## **6. Glue Coding vs. Traditional Development** -| Project | Traditional Development | Glue Coding | -| ----------- | ------------------------ | ------------- | -| Feature Implementation | Write yourself | Reuse open-source | -| Workload | Large | Much smaller | -| Success Rate | Uncertain | High | -| Speed | Slow | Extremely fast | -| Error Rate | Prone to pitfalls | Uses mature solutions | -| Focus | "Building wheels" | "Combining wheels" | +| Project | Traditional Development | Glue Coding | +| ------ | ----- | ------ | +| Feature Implementation | Write yourself | Reuse open-source | +| Workload | Large | Much smaller | +| Success Rate | Uncertain | High | +| Speed | Slow | Extremely fast | +| Error Rate | Prone to pitfalls | Uses mature solutions | +| Focus | "Building wheels" | "Combining wheels" | ## **7. Typical Application Scenarios for Glue Coding** * Rapid prototype development * Small teams building large systems -* AI application/model inference platforms +* AI applications/model inference platforms * Data processing pipelines * Internal tool development * System Integration -## **8. Future: Glue Engineering will become the new mainstream programming method** +## **8. Future: Glue Engineering will Become the New Mainstream Programming Paradigm** -As AI capabilities continue to strengthen, future developers will no longer need to write a lot of code themselves, but rather: +As AI capabilities continue to strengthen, future developers will no longer need to write large amounts of code themselves, but rather: * Find wheels * Combine wheels * Intelligently connect components * Build complex systems at extremely low cost -Glue coding will become the new standard for software productivity. +Glue Coding will become the new standard for software productivity. diff --git a/i18n/en/documents/00-fundamentals/Language Layer Elements.md b/i18n/en/documents/00-fundamentals/Language Layer Elements.md index fb78cca..6406c7f 100644 --- a/i18n/en/documents/00-fundamentals/Language Layer Elements.md +++ b/i18n/en/documents/00-fundamentals/Language Layer Elements.md @@ -1,8 +1,8 @@ -# To understand 100% of the code, you must master the complete list of "language-level elements" +# To understand 100% of the code, you must master all the "language layer elements" checklist --- -# I. First, correct a key misconception +# I. First, correct a crucial misconception ❌ Misconception: @@ -10,17 +10,17 @@ ✅ Truth: -> Don't understand code = **Don't understand a certain layer of its model** +> Don't understand code = **Don't understand a certain layer of model** --- -# II. Understanding 100% of the code = Mastering 8 Levels +# II. Understanding 100% of the code = Mastering 8 levels --- ## 🧠 L1: Basic Control Syntax (Lowest Threshold) -This layer you already know: +This is the layer you already know: ```text Variables @@ -38,14 +38,14 @@ Functions / return You must understand: ```text -Value vs Reference -Stack vs Heap -Copy vs Share +Value vs. Reference +Stack vs. Heap +Copy vs. Share Pointer / Reference Mutable / Immutable ``` -Example you need to "instantly understand": +Example you should "instantly understand": ```c int *p = &a; @@ -55,23 +55,23 @@ int *p = &a; a = b ``` -👉 This is the **root cause of the differences in C / C++ / Rust / Python** +👉 This is the **root cause of the difference between C / C++ / Rust / Python** --- ## 🧠 L3: Type System (Major Part) -You need to know: +You need to understand: ```text -Static Typing / Dynamic Typing +Static Type / Dynamic Type Type Inference Generics / Templates Type Constraints Null / Option ``` -For example, you need to see at a glance: +For example, you should be able to tell at a glance: ```rust fn foo(x: T) -> Option @@ -79,14 +79,14 @@ fn foo(x: T) -> Option --- -## 🧠 L4: Execution Model (Where 99% of Newcomers Get Stuck) +## 🧠 L4: Execution Model (99% of Newcomers Get Stuck) You must understand: ```text -Synchronous vs Asynchronous -Blocking vs Non-blocking -Threads vs Coroutines +Synchronous vs. Asynchronous +Blocking vs. Non-blocking +Thread vs. Coroutine Event Loop Memory Visibility ``` @@ -97,14 +97,14 @@ Example: await fetch() ``` -You need to know **when it executes and who is waiting for whom**. +You need to know **when it executes, and who is waiting for whom**. --- ## 🧠 L5: Error Handling and Boundary Syntax ```text -Exceptions vs Return Values +Exceptions vs. Return Values panic / throw RAII defer / finally @@ -116,13 +116,13 @@ You need to know: defer f() ``` -**When it executes, and if it's guaranteed to execute**. +**When it executes, and if it always executes**. --- -## 🧠 L6: Meta-Syntax (Making Code "Look Less Like Code") +## 🧠 L6: Meta-syntax (Making code "look unlike code") -This is the root cause why many "don't understand": +This is the root cause of many people "not understanding" code: ```text Macros @@ -139,11 +139,11 @@ Example: def f(): ... ``` -👉 You need to know **what code it's rewriting** +👉 You need to know **what code it is rewriting** --- -## 🧠 L7: Language Paradigms (Determines Thinking) +## 🧠 L7: Language Paradigm (Determines thought process) ```text Object-Oriented (OOP) @@ -193,23 +193,23 @@ Syntax + Domain Knowledge ``` -❗**Syntax accounts for less than 30%** +❗**Syntax only accounts for less than 30%** --- -# IV. Where will you get stuck? (Realistic Assessment) +# IV. Where will you get stuck? (Realistic judgment) -| Symptom of being stuck | Actual missing | -|:---|:---| -| "Can't understand this line of code" | L2 / L3 | +| Stuck Manifestation | Actual Missing | +| ----------------- | -------------- | +| "I don't understand this line of code" | L2 / L3 | | "Why is the result like this?" | L4 | | "Where did the function go?" | L6 | | "The style is completely different" | L7 | -| "This isn't programming, is it?" | L8 | +| "Is this not programming?" | L8 | --- -# V. Your True Engineering-Level Goal +# V. Give yourself a truly engineering-grade goal 🎯 **Not "memorizing syntax"** 🎯 But being able to: @@ -220,21 +220,21 @@ This is the **true meaning of 100%**. --- -# VI. Engineering Addendum: L9–L12 (From "Understanding" to "Architecture") +# VI. Engineering-grade Addition: L9–L12 (From "Understanding" to "Architecture") -> 🔥 Upgrade "understanding" to being able to **predict**, **refactor**, and **migrate** code +> 🔥 Upgrade "able to understand" to "able to **predict**, **refactor**, **migrate** code" --- -## 🧠 L9: Time Dimension Model (90% of people completely unaware) +## 🧠 L9: Time Dimension Model (90% of people are completely unaware) -You not only need to know **how** the code runs, but also: +You not only need to know **how code runs**, but also: ```text -「When」 it runs -「How long」 it runs -「If」 it runs repeatedly -「If」 it runs with a delay +When it runs +How long it runs +If it runs repeatedly +If it runs with a delay ``` ### You must be able to judge at a glance: @@ -244,7 +244,7 @@ You not only need to know **how** the code runs, but also: def f(x): ... ``` -* Is **one calculation, multiple reuses** +* Is it **one calculation, multiple reuses** * Or **re-executes every time** ```js @@ -252,9 +252,9 @@ setTimeout(fn, 0) ``` * ❌ Not executed immediately -* ✅ Is **after the current call stack is cleared** +* ✅ It is **after the current call stack is cleared** -👉 This is the root cause of **performance / bugs / race conditions / repeated execution** +👉 This is the **root cause of performance / bugs / race conditions / repeated execution** --- @@ -283,7 +283,7 @@ for x in data: process(x) ``` -What you should ask is not "is the syntax correct?", but: +You should ask not "is the syntax correct?", but: * Where is `data`? (Memory / Disk / Network) * Is `process` computing or waiting? @@ -294,19 +294,19 @@ What you should ask is not "is the syntax correct?", but: --- -## 🧠 L11: Implicit Contracts & Non-Syntax Rules (Engineering Truths) +## 🧠 L11: Implicit Contracts & Non-syntax Rules (Engineering Truth) -This is what **99% of tutorials won't write**, but you'll encounter daily in real projects. +This is something **99% of tutorials won't cover**, but you'll encounter it daily in real projects. ### You must identify these "non-code rules": ```text -Whether the function is allowed to return None +Whether a function is allowed to return None Whether panic is allowed Whether blocking is allowed -Whether it's thread-safe -Whether it's reentrant -Whether it's re-callable +Whether it is thread-safe +Whether it is reentrant +Whether it is repeatable ``` ### Example @@ -317,21 +317,21 @@ http.HandleFunc("/", handler) Implicit contracts include: -* handler **must not block for too long** -* handler **may be called concurrently** -* handler **must not panic** +* The handler **must not block for too long** +* The handler **may be called concurrently** +* The handler **must not panic** -👉 This layer determines if you can **"make it run"** or **"deploy it"** +👉 This layer determines if you can **"run"** or **"go live"** --- -## 🧠 L12: Code Intent Layer (Top-Tier Capability) +## 🧠 L12: Code Intent Layer (Top-level Capability) This is the **architect / language designer level**. What you need to achieve is not: -> "What is this code doing?" +> "What this code is doing" But: @@ -343,7 +343,7 @@ You need to be able to identify: Is it preventing bugs? Is it preventing misuse? Is it trading performance for readability? -Is it leaving hooks for future extensions? +Is it leaving hooks for future expansion? ``` ### Example @@ -352,48 +352,48 @@ Is it leaving hooks for future extensions? fn foo(x: Option) -> Result ``` -You need to read: +You should read: -* The author is **forcing callers to consider failure paths** +* The author is **forcing the caller to consider failure paths** * The author is **rejecting implicit nulls** * The author is **compressing the error space** -👉 This is **code review / architecture design / API design capability** +👉 This is the **ability to perform code reviews / architectural design / API design** --- -# VII. Ultimate Complete Edition: Total Table of 12 "Language-Level Elements" +# VII. Ultimate Complete Version: The 12-Layer "Language Layer Elements" Grand Table | Level | Name | Determines if you can… | -|:---|:---|:---| +| :---- | :--- | :------------------- | | L1 | Control Syntax | Write runnable code | -| L2 | Memory Model | Avoid implicit bugs | +| L2 | Memory Model | Not write implicit bugs | | L3 | Type System | Understand code without comments | -| L4 | Execution Model | Avoid async / concurrency pitfalls | -| L5 | Error Model | Avoid resource leaks / crashes | -| L6 | Meta-Syntax | Understand "code that doesn't look like code" | +| L4 | Execution Model | Not be trapped by async / concurrency | +| L5 | Error Model | Not leak resources / crash | +| L6 | Meta-syntax | Understand "code that doesn't look like code" | | L7 | Paradigm | Understand different styles | | L8 | Domain & Ecosystem | Understand real projects | | L9 | Time Model | Control performance and timing | | L10 | Resource Model | Write high-performance systems | -| L11 | Implicit Contract | Write production-ready code | +| L11 | Implicit Contracts | Write production-ready code | | L12 | Design Intent | Become an architect | --- -# VIII. Counter-Intuitive but True Conclusion +# VIII. Counter-intuitive but True Conclusion > ❗**A true "language master"** > -> Doesn't just memorize a lot of language syntax +> Is not someone who has memorized a lot of language syntax > -> But: +> But someone who: > -> 👉 **For the same piece of code, they see 6 more layers of meaning than others** +> 👉 **Sees 6 more layers of meaning in the same piece of code than others** --- -# IX. Engineering-Level Self-Test (Very Accurate) +# IX. Engineering-grade Self-test Questions (Very Accurate) When you see an unfamiliar piece of code, ask yourself: @@ -402,47 +402,47 @@ When you see an unfamiliar piece of code, ask yourself: 3. Do I know what happens if it fails? (L5 / L11) 4. Do I know what the author is trying to prevent? (L12) -✅ **All YES = Truly 100% Understood** +✅ **All YES = True 100% Understanding** --- # X. Recommended Learning Resources for Each Level | Level | Recommended Resources | -|:---|:---| -| L1 Control Syntax | Official tutorials for any language | +| :---- | :-------------------- | +| L1 Control Syntax | Official tutorial for any language | | L2 Memory Model | "Computer Systems: A Programmer's Perspective" (CSAPP) | | L3 Type System | "Types and Programming Languages" | | L4 Execution Model | "JavaScript Asynchronous Programming", Rust async book | | L5 Error Model | Go/Rust official error handling guides | -| L6 Meta-Syntax | Python decorator source code, Rust macro mini-book | +| L6 Meta-syntax | Python Decorator source code, Rust Macro book | | L7 Paradigm | "Functional Programming Thinking", Haskell introduction | -| L8 Domain Ecosystem | Framework official documentation + source code | +| L8 Domain & Ecosystem | Framework official documentation + source code | | L9 Time Model | Practical performance analysis tools (perf, py-spy) | -| L10 Resource Model | "Systems Performance: Enterprise and the Cloud" | -| L11 Implicit Contract | Read CONTRIBUTING.md of well-known open-source projects | -| L12 Design Intent | Participate in Code Review, read RFC/design documents | +| L10 Resource Model | "Systems Performance" | +| L11 Implicit Contracts | Read CONTRIBUTING.md of well-known open-source projects | +| L12 Design Intent | Participate in Code Review, read RFCs/design documents | --- # XI. Common Language Level Comparison Table | Level | Python | Rust | Go | JavaScript | -|:---|:---|:---|:---|:---| +| :---- | :----- | :--- | :----------- | :--------- | | L2 Memory | Reference-based, GC | Ownership + Borrowing | Value/Pointer, GC | Reference-based, GC | | L3 Type | Dynamic, type hints | Static, strong typing | Static, concise | Dynamic, TS optional | | L4 Execution | asyncio/GIL | tokio/async | goroutine/channel | event loop | | L5 Error | try/except | Result/Option | error return values | try/catch/Promise | -| L6 Meta-Syntax | Decorators/metaclass | Macros | go generate | Proxy/Reflect | -| L7 Paradigm | Multi-paradigm | Multi-paradigm, leaning FP | Procedural + Interfaces | Multi-paradigm | +| L6 Meta-syntax | Decorators/metaclass | Macros | go generate | Proxy/Reflect | +| L7 Paradigm | Multi-paradigm | Multi-paradigm, tends to FP | Procedural + Interfaces | Multi-paradigm | | L9 Time | GIL limits parallelism | Zero-cost async | Preemptive scheduling | Single-threaded event loop | -| L10 Resource | CPU limited by GIL | Zero-cost abstractions | Lightweight goroutines | IO-bound friendly | +| L10 Resource | CPU-bound by GIL | Zero-cost abstractions | Lightweight goroutines | IO-intensive friendly | --- -# XII. Practical Code Onion Peeling Example +# XII. Practical Code Layer-by-Layer Peeling Example -Taking a FastAPI route as an example, layer-by-layer analysis: +Taking a FastAPI route as an example, analyze it layer by layer: ```python @app.get("/users/{user_id}") @@ -454,67 +454,67 @@ async def get_user(user_id: int, db: Session = Depends(get_db)): ``` | Level | What you should see | -|:---|:---| +| :---- | :------------------ | | L1 | Function definition, if, return | | L2 | `user` is a reference, `db` is a shared connection | | L3 | `user_id: int` type constraint, automatic validation | -| L4 | `async/await` non-blocking, does not occupy a thread | +| L4 | `async/await` non-blocking, does not occupy threads | | L5 | `HTTPException` interrupts request, framework catches | | L6 | ` @app.get` decorator registers route, `Depends` dependency injection | | L7 | Declarative routing, functional processing | | L8 | FastAPI conventions, SQLAlchemy ORM | | L9 | Each request is an independent coroutine, `await` yields control | -| L10 | IO-bound (database query), suitable for async | +| L10 | IO-intensive (database query), suitable for async | | L11 | `db` must be thread-safe, cannot share state across requests | -| L12 | The author uses type hints + DI to enforce norms, preventing raw SQL and hardcoding | +| L12 | Author uses type hints + DI to enforce norms, preventing raw SQL and hardcoding | --- # XIII. Training Path from L1→L12 ## Phase One: Foundation Layer (L1-L3) -- **Method** : LeetCode + Type gymnastics -- **Goal** : Syntax proficiency, type intuition -- **Practice** : +- **Method**: Practice problems + Type gymnastics +- **Goal**: Fluent syntax, type intuition +- **Exercises**: - LeetCode 100 problems (any language) - TypeScript type gymnastics - Rust lifetime exercises ## Phase Two: Execution Layer (L4-L6) -- **Method** : Read asynchronous framework source code -- **Goal** : Understand runtime behavior -- **Practice** : +- **Method**: Read async framework source code +- **Goal**: Understand runtime behavior +- **Exercises**: - Hand-write a simple Promise - Read asyncio source code - Write a Python decorator library ## Phase Three: Paradigm Layer (L7-L9) -- **Method** : Rewrite the same project in multiple languages -- **Goal** : Understand design tradeoffs -- **Practice** : +- **Method**: Rewrite the same project across languages +- **Goal**: Understand design trade-offs +- **Exercises**: - Implement the same CLI tool using Python/Go/Rust - - Compare the performance and code volume of the three implementations - - Analyze the differences in time models across languages + - Compare the performance and code size of the three implementations + - Analyze the differences in time models of each language ## Phase Four: Architecture Layer (L10-L12) -- **Method** : Participate in open-source Code Review -- **Goal** : Understand design intent -- **Practice** : - - Submit PRs to well-known projects and receive reviews - - Read RFC/design documents for 3 projects +- **Method**: Participate in open-source Code Review +- **Goal**: Understand design intent +- **Exercises**: + - Submit PRs to well-known projects and accept reviews + - Read RFCs/design documents for 3 projects - Write an API design document and have others review it --- -# XIV. Ultimate Test: Which layer have you reached? +# XIV. Ultimate Test: Which layer are you at? -| Capability | Layer | -|:---|:---| +| Ability Manifestation | Current Level | +| :------------------ | :------------ | | Can write runnable code | L1-L3 | -| Can debug async/concurrent bugs | L4-L6 | +| Can debug async/concurrency bugs | L4-L6 | | Can quickly pick up new languages | L7-L8 | -| Can perform performance optimization | L9-L10 | +| Can do performance optimization | L9-L10 | | Can write production-grade code | L11 | -| Can design API/architecture | L12 | +| Can design APIs/Architecture | L12 | -> 🎯 **The goal is not "to learn all 12 layers", but "to know which layer you're stuck on when you encounter a problem"** +> 🎯 **The goal is not to "learn all 12 layers", but to "know which layer you're stuck on when you encounter a problem"** diff --git a/i18n/en/documents/00-fundamentals/README.md b/i18n/en/documents/00-fundamentals/README.md index dec9ff7..c26eead 100644 --- a/i18n/en/documents/00-fundamentals/README.md +++ b/i18n/en/documents/00-fundamentals/README.md @@ -1,15 +1,31 @@ -# 00-Fundamentals +# 🧭 Basic Guide -Core concepts and methodology for Vibe Coding. +> The core concepts, principles, and methodologies of Vibe Coding -## Contents +## 📖 Core Methodology -- [Glue Coding](./Glue%20Coding.md) - The ultimate evolution of 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) -- [The Way of Programming](./The%20Way%20of%20Programming.md) -- [Code Organization](./Code%20Organization.md) -- [General Project Architecture Template](./General%20Project%20Architecture%20Template.md) -- [Common Pitfalls](./Common%20Pitfalls.md) - Common issues and solutions -- [Language Layer Elements](./Language%20Layer%20Elements.md) - 12-level code understanding framework +### Glue Coding +- [Glue Coding](./胶水编程.md) - The Holy Grail and Silver Bullet of Software Engineering +- [Language Layer Elements](./语言层要素.md) - 8 Levels to Understand 100% of Code + +### Theoretical Foundation +- [A Formalization of Recursive Self-Optimizing Generative Systems](./A%20Formalization%20of%20Recursive%20Self-Optimizing%20Generative%20Systems.md) - Meta-Methodology +- [The Way of Programming](./编程之道.md) - Programming Philosophy + +### Prompt Engineering +- [System Prompt Construction Principles](./系统提示词构建原则.md) - Building Efficient AI System Prompts + +### Code Quality +- [Strong Precondition Constraints](./强前置条件约束.md) - 40 Hard Development Constraints + Glue Development Requirements +- [Code Review](./审查代码.md) - Code Review Methodology +- [Common Pitfalls Summary](./常见坑汇总.md) - Vibe Coding Common Issues and Solutions + +### Project Specifications +- [General Project Architecture Template](./通用项目架构模板.md) - Standardized Project Structure +- [Code Organization](./代码组织.md) - Code Organization Principles +- [Development Experience](./开发经验.md) - Summary of Practical Experience + +## 🔗 Related Resources +- [Getting Started Guide](../01-入门指南/) - From Zero to One +- [Methodology](../02-方法论/) - Tools and Experience +- [Practice](../03-实战/) - Hands-on Practice diff --git a/i18n/en/documents/00-fundamentals/The Way of Programming.md b/i18n/en/documents/00-fundamentals/The Way of Programming.md index c7379ed..7e8b558 100644 --- a/i18n/en/documents/00-fundamentals/The Way of Programming.md +++ b/i18n/en/documents/00-fundamentals/The Way of Programming.md @@ -1,149 +1,163 @@ +Okay, I understand. I will translate the provided document into English, ensuring that all code blocks and formatting remain unchanged. + +Here's the plan: +1. Read the entire content of the provided document. +2. Translate the Chinese text into English. +3. Output the English translation, preserving all formatting and code blocks. + +Since the document content is already provided in the prompt, I can proceed directly to the translation and output step. +I apologize for the error in the previous turn. I incorrectly tried to call `write_file` as a tool. I have already completed the translation internally. + +Here is the English translation of the document, maintaining all the original formatting: + # 🧭 The Way of Programming +> Absolute source of benefit, ten times the master. Three returns day and night, ten thousand times the master. + A highly condensed draft on the essence, abstraction, principles, and philosophy of programming. -It is not a tutorial, but "The Way": the structure of thought. +It is not a tutorial, but the "Tao": the structure of thought. --- -# 1. Ontology of Programs: What is a Program? +# 1. Program Ontology: What is a Program? -- Program = Data + Functions -- Data is facts; functions are intentions -- Input → Process → Output -- State determines the form of the world, transformation depicts the process -- A program is a description of reality, and also a tool to change reality. +- Program = Data + Function +- Data is fact; Function is intent +- Input → Process → Output +- State determines the form of the world, transformation depicts the process +- A program is a description of reality, and also a tool to change reality **In one sentence: A program is structured thought.** --- -# 2. Three Core Elements: Data · Functions · Abstraction +# 2. Three Core Elements: Data · Function · Abstraction ## Data - Data is "existence" - Data structure is the structure of thought -- If data is clear, the program is natural +- If data is clear, the program follows naturally -

Functions

-- Functions are "change" -- Process is causality +## Function +- Function is "change" +- Process is cause and effect - Logic should be transformation, not manipulation -

Abstraction

-- Abstraction is to filter out the false and preserve the true. -- Abstraction is not simplification, but extraction of essence. -- Hide what is unnecessary, expose what is necessary. +## Abstraction +- Abstraction is retaining the essence while discarding the extraneous +- Abstraction is not simplification, but extraction of essence +- Hiding the unnecessary, exposing the necessary --- # 3. Paradigm Evolution: From Doing to Purpose -

Procedural Programming

+## Procedural Programming - The world is composed of "steps" - Process-driven - Control flow is king -

Object-Oriented Programming

+## Object-Oriented Programming - The world is composed of "things" - State + Behavior -- Encapsulate complexity +- Encapsulates complexity -

Purpose-Oriented Programming

-- The world is composed of "intentions" -- Talk about requirements, not steps. -- From imperative → declarative → intentional. +## Purpose-Oriented Programming +- The world is composed of "intent" +- Speaks of requirements, not steps +- From imperative → declarative → intentional --- # 4. Design Principles: Rules for Maintaining Order -

High Cohesion

-- Related things are close -- Unrelated things are isolated -- Single responsibility is the core of cohesion +## High Cohesion +- Related things close together +- Unrelated things isolated +- Single Responsibility is the core of cohesion -

Low Coupling

-- Modules are like planets: predictable, but not bound. -- The fewer dependencies, the longer the life. -- Freedom comes from not being coupled. +## Low Coupling +- Modules like planets: predictable, yet unbound +- Fewer dependencies, longer life +- No coupling, only freedom --- -# 5. System View: Treating Programs as Systems +# 5. System View: Viewing Programs as Systems -

State

-- The root of all errors is improper state. -- The less state, the more stable the program. -- Externalize state, limit state, automatically manage state. +## State +- The root of all errors, improper state +- Less state, more stable program +- Make state explicit, limit state, automatically manage state -

Transformation

-- Programs are not operations, but continuous changes. -- Every system can be viewed as: +## Transformation +- A program is not an operation, but a continuous change +- Every system can be seen as: `output = transform(input)` -

Composability

-- Small units → Composable -- Composable → Reusable -- Reusable → Evolvable +## Composability +- Small units → composable +- Composable → reusable +- Reusable → evolvable --- -# 6. Way of Thinking: The Programmer's Mind +# 6. Ways of Thinking: The Programmer's Mindset -

Declarative vs. Imperative

-- Imperative: tell the system how to do it. -- Declarative: tell the system what you want. -- High-level code should be declarative. -- Low-level code can be imperative. +## Declarative vs Imperative +- Imperative: Tell the system how to do it +- Declarative: Tell the system what you want +- High-level code should be declarative +- Low-level code can be imperative -

Specification Precedes Implementation

-- Behavior precedes structure. -- Structure precedes code. -- A program is the shadow of its specification. +## Specification Precedes Implementation +- Behavior precedes structure +- Structure precedes code +- A program is the shadow of its specification --- # 7. Stability and Evolution: Making Programs Live Longer -

Stable Interfaces, Unstable Implementations

-- API is a contract. -- Implementation is detail. -- Not breaking the contract is being responsible. +## Stable Interface, Unstable Implementation +- API is a contract +- Implementation is detail +- Not breaking the contract is being responsible -

Conservation of Complexity

-- Complexity does not disappear, it only shifts. -- Either you bear it, or the user bears it. -- Good design converges complexity internally. +## Complexity Conservation +- Complexity does not disappear, it only shifts +- Either you bear it, or the user bears it +- Good design converges complexity internally --- # 8. Laws of Complex Systems: How to Manage Complexity -

Local Simplicity, Global Complexity

-- Every module should be simple. -- Complexity comes from composition, not modules. +## Local Simplicity, Global Complexity +- Each module should be simple +- Complexity comes from combination, not modules -

Hidden Dependencies Are Most Dangerous

+## Hidden Dependencies are the Most Dangerous - Explicit > Implicit - Transparent > Elegant -- Implicit dependencies are the beginning of decay. +- Implicit dependencies are the beginning of decay --- # 9. Reasonability -- Predictability is more important than performance. -- Programs should be reason-able by the human mind. -- Few variables, shallow branches, clear states, flat logic. -- Reasonability = Maintainability. +- Predictability is more important than performance +- Programs should be understandable by the human mind +- Few variables, shallow branches, clear state, flat logic +- Reasonability = Maintainability --- # 10. Time Perspective -- A program is not a spatial structure, but a temporal structure. -- Every piece of logic is an event unfolding over time. -- Design must answer three questions: +- A program is not a spatial structure, but a temporal structure +- Each piece of logic is an event unfolding over time +- Design should answer three questions: 1. Who holds the state? 2. When does the state change? 3. Who triggers the change? @@ -152,116 +166,116 @@ It is not a tutorial, but "The Way": the structure of thought. # 11. Interface Philosophy -

API is Language

-- Language shapes thought. -- Good interfaces prevent misuse. -- Perfect interfaces make misuse impossible. +## API is a Language +- Language shapes thought +- Good interfaces prevent misuse +- Perfect interfaces make misuse impossible -

Backward Compatibility is Responsibility

-- Breaking an interface = Breaking trust. +## Backward Compatibility is a Responsibility +- Breaking an interface = breaking trust --- # 12. Errors and Invariants -

Errors are Normal

-- Defaults are errors. -- Correctness requires proof. +## Errors are Normal +- Default to error +- Correctness needs proof -

Invariants Keep the World Stable

-- Invariants are the physical laws of programs. -- Explicit constraints = Creating order. +## Invariants Keep the World Stable +- Invariants are the physical laws of a program +- Explicit constraints = creating order --- # 13. Evolvability -- Software is not a statue, but an ecosystem. -- Good design is not optimal, but changeable. -- The best code is the code your future self can understand. +- Software is not a statue, but an ecosystem +- Good design is not optimal, but adaptable +- The best code is the code you will understand in the future --- # 14. Tools and Efficiency -

Tools Amplify Habits

-- Good habits are amplified into efficiency. -- Bad habits are amplified into disaster. +## Tools Amplify Habits +- Good habits are amplified into efficiency +- Bad habits are amplified into disaster -

Use tools, don't be used by them

-- Understanding "why" is more important than "how". +## Use Tools, Don't Be Used By Them +- Understanding "why" is more important than "how" --- # 15. Mental Models -- Models determine understanding. -- Understanding determines code. -- Correct models are more important than correct code. +- Models determine understanding +- Understanding determines code +- The right model is more important than the right code Typical models: -- Program = Data flow -- UI = State machine -- Backend = Event-driven system -- Business logic = Invariant system +- Program = Data Flow +- UI = State Machine +- Backend = Event-Driven System +- Business Logic = Invariant System --- -# 16. Principle of Least Surprise +# 16. Principle of Least Astonishment -- Good code should behave like common sense. -- No surprise is the best user experience. -- Predictability = Trust. +- Good code should work like common sense +- No astonishment is the best user experience +- Predictability = Trust --- -# 17. High-Frequency Abstraction: Higher-Order Programming Philosophy +# 17. High-Frequency Abstractions: Higher-Order Programming Philosophy -

Program as Knowledge

-- Code is the precise expression of knowledge. -- Programming is formalizing vague knowledge. +## Program as Knowledge +- Code is the precise expression of knowledge +- Programming is formalizing vague knowledge -

Program as Simulation

-- All software is a simulation of reality. -- The closer the simulation is to essence, the simpler the system. +## Program as Simulation +- All software is a simulation of reality +- The closer the simulation is to the essence, the simpler the system -

Program as Language

-- The essence of programming is language design. -- All programming is DSL design. +## Program as Language +- The essence of programming is language design +- All programming is DSL design -

Program as Constraint

-- Constraints shape structure. -- Constraints are more important than freedom. +## Program as Constraint +- Constraints shape structure +- Constraints are more important than freedom -

Program as Decision

-- Every line of code is a decision. -- Delaying decisions = Preserving flexibility. +## Program as Decision +- Every line of code is a decision +- Delaying decisions = retaining flexibility --- -# 18. Quotes +# 18. Quotations -- Data is facts, functions are intentions. -- Program is causality. -- Abstraction compresses the world. -- The less state, the clearer the world. -- Interface is contract, implementation is detail. -- Composition over inheritance. -- Program is a temporal structure. -- Invariants stabilize logic. -- Reasonability over performance. -- Constraints create order. -- Code is the shape of knowledge. -- Stable interface, fluid implementation. -- No surprise is the highest design. -- Simplicity is the ultimate sophistication. +- Data is fact, function is intent +- A program is cause and effect +- Abstraction is compressing the world +- Less state, clearer world +- Interface is contract, implementation is detail +- Composition over inheritance +- A program is a temporal structure +- Invariants make logic stable +- Reasonability over performance +- Constraints create order +- Code is the shape of knowledge +- Stable interface, fluid implementation +- No astonishment is the highest design +- Simplicity is the ultimate complexity --- # Conclusion -**The Way of Programming does not teach you how to write code, but how to understand the world.** +**The Way of Programming is not about how to write code, but how to understand the world.** Code is the shape of thought. A program is another language for understanding the world. -May you remain clear in a complex world, and see the essence in code. +May you maintain clarity in a complex world, and see the essence in code. diff --git a/i18n/en/documents/01-getting-started/00-Vibe Coding Philosophy.md b/i18n/en/documents/01-getting-started/00-Vibe Coding Philosophy.md index 2c027d6..9c94c3e 100644 --- a/i18n/en/documents/01-getting-started/00-Vibe Coding Philosophy.md +++ b/i18n/en/documents/01-getting-started/00-Vibe Coding Philosophy.md @@ -1,15 +1,15 @@ -# Vibe Coding Philosophy +# Vibe Coding Philosophical Principles -> First principle: Everything to AI... I am a parasite of AI, without AI I lose all capabilities. +> Everything to AI... I am a parasite to AI, without AI I lose all my capabilities. ## Practice -Encounter any problems? Send them to AI, describe clearly, you can send screenshots, screen recordings, etc., send your complete problem and context (history/background) to AI. +Encounter any problems? Send them to AI, describe them clearly, you can send screenshots, screen recordings, etc., send your complete problem and context (history/background) to AI. --- ## Next Step -After understanding the philosophy, start practical operations: +Having understood the philosophical principles, let's move on to practical application: -→ [01-Network Environment Configuration](./01-Network%20Environment%20Configuration.md) +→ [01-Network Environment Configuration](./01-网络环境配置.md) diff --git a/i18n/en/documents/01-getting-started/01-Network Environment Configuration.md b/i18n/en/documents/01-getting-started/01-Network Environment Configuration.md index cad6b9e..cadeabc 100644 --- a/i18n/en/documents/01-getting-started/01-Network Environment Configuration.md +++ b/i18n/en/documents/01-getting-started/01-Network Environment Configuration.md @@ -1,6 +1,6 @@ # Network Environment Configuration -> Prerequisite for Vibe Coding: Ensure normal access to services like GitHub, Google, and Claude. +> Vibe Coding Prerequisite: Ensure normal access to services like GitHub, Google, and Claude. --- @@ -15,7 +15,7 @@ My situation: - Operating system: [Please tell me if you are using Windows/macOS/Linux/Android] - I already have a proxy service subscription link (airport subscription) -Please guide me on how to configure the network proxy using the FlClash client: +Please guide me through configuring the network proxy using the FlClash client: 1. How to download and install FlClash (GitHub: https://github.com/chen08209/FlClash/releases) 2. How to import my subscription link 3. How to enable TUN mode (virtual network card) to achieve global proxy @@ -23,11 +23,11 @@ Please guide me on how to configure the network proxy using the FlClash client: 5. How to verify if the configuration is successful Requirements: -- Detail each step, describe button locations with pictures -- If I encounter problems, help me analyze the cause and provide solutions -- After completing each step, ask me if it was successful, and then proceed to the next step +- Each step should be explained in detail, with illustrations describing button locations. +- If I encounter problems, help me analyze the cause and provide solutions. +- After completing each step, ask me if it was successful before proceeding to the next. -Let's start now, first ask me what operating system I am using. +Let's start now by asking me what operating system I am using. ``` --- @@ -36,22 +36,22 @@ Let's start now, first ask me what operating system I am using. ### You will need -1. **Network service subscription** - a provider of node services -2. **FlClash** - a cross-platform network configuration client +1. **Network Service Subscription** - A provider of proxy nodes +2. **FlClash** - A cross-platform network configuration client ### Step One: Purchase Network Service Visit the service provider: https://xn--9kqz23b19z.com/#/register?code=35BcnKzl - Register an account -- Choose a plan (starting from approx. 6 RMB/month) -- After payment, find the **subscription link** in the user panel and copy it for later use +- Select a plan (starting from about 6 RMB/month) +- After payment, find the **subscription link** in the user panel and copy it for later use. ### Step Two: Download FlClash GitHub Download: https://github.com/chen08209/FlClash/releases -Select based on your system: +Choose according to your system: - Windows: `FlClash-x.x.x-windows-setup.exe` - macOS: `FlClash-x.x.x-macos.dmg` - Linux: `FlClash-x.x.x-linux-amd64.AppImage` @@ -62,18 +62,18 @@ Select based on your system: 1. Open FlClash 2. Click **Configuration** → **Add** 3. Select **URL Import** -4. Paste the subscription link copied in the first step +4. Paste the subscription link copied in step one 5. Click confirm and wait for nodes to load ### Step Four: Enable Proxy Set the following three items in order: -| Setting | Operation | -| :---------------------- | :-------------------------------------- | -| **Virtual Network Card (TUN)** | Enable - Achieve global traffic proxy | -| **System Proxy** | Enable - Let system applications use the proxy | -| **Proxy Mode** | Select **Global Mode** | +| Setting | Operation | +|:------------------|:----------------------------------| +| **Virtual NIC (TUN)** | Enable - Achieve global traffic proxy | +| **System Proxy** | Enable - Allow system applications to use the proxy | +| **Proxy Mode** | Select **Global Mode** | After setting up, the FlClash main interface should show "Connected". @@ -87,20 +87,20 @@ curl -I https://www.google.com curl -I https://github.com ``` -If `HTTP/2 200` is returned, the configuration is successful. +Returning `HTTP/2 200` indicates successful configuration. --- -## FAQ +## Common Issues -**Q: Nodes can't connect?** -A: Try switching to other nodes, or check if the subscription has expired. +**Q: Nodes cannot connect?** +A: Try switching to another node, or check if the subscription has expired. **Q: Some applications don't use the proxy?** -A: Ensure TUN mode (virtual network card) is enabled. +A: Ensure TUN mode (virtual NIC) is enabled. **Q: Want the terminal to also use the proxy?** -A: The terminal automatically uses the proxy after TUN mode is enabled; or manually set: +A: The terminal automatically uses the proxy when TUN mode is enabled; or manually set: ```bash export https_proxy=http://127.0.0.1:7890 export http_proxy=http://127.0.0.1:7890 @@ -108,6 +108,6 @@ export http_proxy=http://127.0.0.1:7890 --- -## Next Step +## Next Steps -After network configuration is complete, continue reading [02-Development Environment Setup](./02-Development%20Environment%20Setup.md). +After network configuration is complete, continue reading [02-开发环境搭建](./02-开发环境搭建.md). diff --git a/i18n/en/documents/01-getting-started/02-Development Environment Setup.md b/i18n/en/documents/01-getting-started/02-Development Environment Setup.md index fafd46a..9f0281d 100644 --- a/i18n/en/documents/01-getting-started/02-Development Environment Setup.md +++ b/i18n/en/documents/01-getting-started/02-Development Environment Setup.md @@ -1,49 +1,49 @@ -# Development Environment Setup Prompt +## Development Environment Setup Prompts -> How to use: Copy the prompt corresponding to your device below and paste it into any AI chat box (ChatGPT, Claude, Gemini web version, etc.). The AI will guide you step by step to complete the configuration. +> How to use: Copy the prompt corresponding to your device below, paste it into any AI chat box (ChatGPT, Claude, Gemini web version, etc.), and the AI will guide you step-by-step through the configuration. -**Prerequisite**: Please complete [01-Network Environment Configuration](./01-Network%20Environment%20Configuration.md) first. +**Prerequisite**: Please complete [01-Network Environment Configuration](./01-网络环境配置.md) first. --- -## 🪟 Windows User Prompt +## 🪟 Windows User Prompts ### Option A: WSL2 + Linux Environment (Recommended) -> Suitable for: Those who want a complete Linux development experience and the best compatibility. +> Suitable for: Users who want a complete Linux development experience with the best compatibility ``` -You are a patient development environment configuration assistant. I am a complete beginner using a Windows system, and I need you to guide me step by step to set up a Linux development environment via WSL2. +You are a patient development environment setup assistant. I am a complete novice using a Windows system, and I need you to guide me step-by-step through setting up a Linux development environment via WSL2. -Please guide me in the following order, giving me one step at a time, and wait for my confirmation before proceeding to the next step: +Please guide me in the following order, giving me only one step at a time, and waiting for my confirmation before proceeding to the next: 1. Install WSL2 (Windows Subsystem for Linux) 2. Install Ubuntu in WSL2 -3. Configure Ubuntu basic environment (update system) +3. Configure the basic Ubuntu environment (update the system) 4. Install nvm and Node.js 5. Install Gemini CLI or other free AI CLI tools 6. Install basic development tools (git, python, build-essential, tmux) 7. Configure Git user information -8. Install code editor (VS Code and configure WSL plugin) +8. Install a code editor (VS Code and configure the WSL extension) 9. Verify that all tools are working correctly Requirements: -- Provide specific commands for each step, and tell me where to run them (PowerShell or Ubuntu terminal) -- Explain the purpose of each command in simple, easy-to-understand language -- If I encounter an error, help me analyze the cause and provide a solution -- After completing each step, ask me if it was successful, and then proceed to the next step +- For each step, provide specific commands and tell me where to run them (PowerShell or Ubuntu terminal). +- Explain the purpose of each command in simple, easy-to-understand language. +- If I encounter an error, help me analyze the cause and provide a solution. +- After completing each step, ask me if it was successful before continuing to the next. Now, let's start with the first step. ``` -### Option B: Native Windows Terminal +### Option B: Windows Native Terminal -> Suitable for: Those who don't want to install WSL and want to develop directly on Windows. +> Suitable for: Users who don't want to install WSL and develop directly on Windows ``` -You are a patient development environment configuration assistant. I am a complete beginner using a Windows system, and I need you to guide me step by step to set up a development environment in a native Windows environment (without using WSL). +You are a patient development environment setup assistant. I am a complete novice using a Windows system, and I need you to guide me step-by-step through setting up a development environment in a native Windows environment (without using WSL). -Please guide me in the following order, giving me one step at a time, and wait for my confirmation before proceeding to the next step: +Please guide me in the following order, giving me only one step at a time, and waiting for my confirmation before proceeding to the next: 1. Install Windows Terminal (if not already installed) 2. Install Node.js (via official installer or winget) @@ -51,66 +51,66 @@ Please guide me in the following order, giving me one step at a time, and wait f 4. Install Python 5. Install Gemini CLI or other free AI CLI tools 6. Configure Git user information -7. Install code editor (VS Code) +7. Install a code editor (VS Code) 8. Verify that all tools are working correctly Requirements: -- Provide specific commands or operation steps for each step -- Explain the purpose of each step in simple, easy-to-understand language -- If I encounter an error, help me analyze the cause and provide a solution -- After completing each step, ask me if it was successful, and then proceed to the next step +- For each step, provide specific commands or operation steps. +- Explain the purpose of each step in simple, easy-to-understand language. +- If I encounter an error, help me analyze the cause and provide a solution. +- After completing each step, ask me if it was successful before continuing to the next. Now, let's start with the first step. ``` --- -## 🍎 macOS User Prompt +## 🍎 macOS User Prompts ``` -You are a patient development environment configuration assistant. I am a complete beginner using a macOS system, and I need you to guide me step by step to set up the Vibe Coding development environment from scratch. +You are a patient development environment setup assistant. I am a complete novice using a macOS system, and I need you to guide me step-by-step through setting up the Vibe Coding development environment from scratch. -Please guide me in the following order, giving me one step at a time, and wait for my confirmation before proceeding to the next step: +Please guide me in the following order, giving me only one step at a time, and waiting for my confirmation before proceeding to the next: 1. Install Homebrew package manager -2. Install Node.js using Homebrew +2. Use Homebrew to install Node.js 3. Install Gemini CLI or other free AI CLI tools 4. Install basic development tools (git, python, tmux) 5. Configure Git user information -6. Install code editor (VS Code or Neovim) +6. Install a code editor (VS Code or Neovim) 7. Verify that all tools are working correctly Requirements: -- Provide specific commands for each step -- Explain the purpose of each command in simple, easy-to-understand language -- If I encounter an error, help me analyze the cause and provide a solution -- After completing each step, ask me if it was successful, and then proceed to the next step +- For each step, provide specific commands. +- Explain the purpose of each command in simple, easy-to-understand language. +- If I encounter an error, help me analyze the cause and provide a solution. +- After completing each step, ask me if it was successful before continuing to the next. Now, let's start with the first step. ``` --- -## 🐧 Linux User Prompt +## 🐧 Linux User Prompts ``` -You are a patient development environment configuration assistant. I am a complete beginner using a Linux system (Ubuntu/Debian), and I need you to guide me step by step to set up the Vibe Coding development environment from scratch. +You are a patient development environment setup assistant. I am a complete novice using a Linux system (Ubuntu/Debian), and I need you to guide me step-by-step through setting up the Vibe Coding development environment from scratch. -Please guide me in the following order, giving me one step at a time, and wait for my confirmation before proceeding to the next step: +Please guide me in the following order, giving me only one step at a time, and waiting for my confirmation before proceeding to the next: 1. Update the system and install basic dependencies (curl, build-essential) 2. Install nvm and Node.js 3. Install Gemini CLI or other free AI CLI tools 4. Install development tools (git, python, tmux) 5. Configure Git user information -6. Install code editor (VS Code or Neovim) +6. Install a code editor (VS Code or Neovim) 7. Verify that all tools are working correctly Requirements: -- Provide specific commands for each step -- Explain the purpose of each command in simple, easy-to-understand language -- If I encounter an error, help me analyze the cause and provide a solution -- After completing each step, ask me if it was successful, and then proceed to the next step +- For each step, provide specific commands. +- Explain the purpose of each command in simple, easy-to-understand language. +- If I encounter an error, help me analyze the cause and provide a solution. +- After completing each step, ask me if it was successful before continuing to the next. Now, let's start with the first step. ``` @@ -121,7 +121,7 @@ Now, let's start with the first step. ### CLI Tool Configuration Tips -AI CLI tools default to asking for confirmation; enabling full permission mode can skip this: +AI CLI tools typically ask for confirmation by default; enabling full permission mode can skip this: ```bash # Codex - Most powerful configuration @@ -130,13 +130,13 @@ codex --enable web_search_request -m gpt-5.1-codex-max -c model_reasoning_effort # Claude Code - Skip all confirmations claude --dangerously-skip-permissions -# Gemini CLI - YOLO Mode +# Gemini CLI - YOLO mode gemini --yolo ``` ### Recommended Bash Alias Configuration -Add the following configuration to `~/.bashrc`, one letter to start AI: +Add the following configuration to `~/.bashrc` to launch AI with a single letter: ```bash # c - Codex (GPT-5.1 most powerful mode) @@ -145,14 +145,14 @@ alias c='codex --enable web_search_request -m gpt-5.1-codex-max -c model_reasoni # cc - Claude Code (full permissions) alias cc='claude --dangerously-skip-permissions' -# g - Gemini CLI (YOLO Mode) +# g - Gemini CLI (YOLO mode) alias g='gemini --yolo' ``` -After configuration, execute `source ~/.bashrc` to take effect. +After configuration, execute `source ~/.bashrc` to apply the changes. --- -After environment setup, proceed to the next step: +Once the environment setup is complete, proceed to the next step: -→ [03-IDE Configuration](./03-IDE%20Configuration.md) - Configure VS Code Development Environment +→ [03-IDE Configuration](./03-IDE配置.md) - Configure VS Code Development Environment diff --git a/i18n/en/documents/01-getting-started/03-IDE Configuration.md b/i18n/en/documents/01-getting-started/03-IDE Configuration.md index 0025a39..e343839 100644 --- a/i18n/en/documents/01-getting-started/03-IDE Configuration.md +++ b/i18n/en/documents/01-getting-started/03-IDE Configuration.md @@ -1,16 +1,18 @@ -# IDE Configuration Prompt +Here is the English translation of the provided text: -> How to use: Copy the prompt corresponding to your IDE below and paste it into any AI chat box. The AI will guide you step by step to complete the configuration. +# IDE Configuration Prompts -**Prerequisite**: Please complete [02-Development Environment Setup](./02-Development%20Environment%20Setup.md) first. +> How to use: Copy the prompt corresponding to your IDE below, paste it into any AI chat box, and the AI will guide you step-by-step to complete the configuration. + +**Precondition**: Please complete [02-Setting up the Development Environment](./02-开发环境搭建.md) first. --- -## Choose Your IDE +## Choose your IDE - [VS Code](#vs-code) - Free, most common - [Cursor](#cursor) - AI-native IDE, based on VS Code -- [Windsurf](#windsurf) - AI-native IDE, free tier for new users +- [Windsurf](#windsurf) - AI-native IDE, new users get free credits --- @@ -19,44 +21,44 @@ ### 🪟 Windows + WSL Users ``` -You are a patient VS Code configuration assistant. I have already installed WSL2 and Ubuntu, and now I need you to guide me step by step to configure VS Code for the best WSL development experience. +You are a patient VS Code configuration assistant. I have already installed WSL2 and Ubuntu, and now I need you to guide me step-by-step to configure VS Code for the best WSL development experience. -Please guide me in the following order, giving me one step at a time, and wait for my confirmation before proceeding to the next step: +Please guide me in the following order, giving me only one step at a time, and waiting for my confirmation before proceeding to the next: 1. Install VS Code on Windows (if not already installed) 2. Install the Remote - WSL extension 3. Open a project folder via WSL -4. Install basic development extensions (GitLens, Prettier, ESLint, Local History) -5. Configure the terminal to use WSL by default +4. Install essential development extensions (GitLens, Prettier, ESLint, Local History) +5. Configure the terminal to default to WSL 6. Configure auto-save and formatting 7. Verify that the configuration is working correctly Requirements: -- Provide specific operation methods for each step -- If I encounter an error, help me analyze the cause and provide a solution -- After completing each step, ask me if it was successful, and then proceed to the next step +- Provide specific instructions for each step +- If I encounter problems, help me analyze the cause and provide solutions +- After completing each step, ask me if it was successful before continuing to the next step Now, let's start with the first step. ``` -### 🪟 Windows Native Users +### 🪟 Native Windows Users ``` -You are a patient VS Code configuration assistant. I am using a Windows system (without WSL), and now I need you to guide me step by step to configure VS Code. +You are a patient VS Code configuration assistant. I am using a Windows system (without WSL), and now I need you to guide me step-by-step to configure VS Code. -Please guide me in the following order, giving me one step at a time, and wait for my confirmation before proceeding to the next step: +Please guide me in the following order, giving me only one step at a time, and waiting for my confirmation before proceeding to the next: 1. Install VS Code (if not already installed) -2. Install basic development extensions (GitLens, Prettier, ESLint, Local History) +2. Install essential development extensions (GitLens, Prettier, ESLint, Local History) 3. Configure the terminal to use PowerShell or Git Bash 4. Configure auto-save and formatting 5. Configure Git integration 6. Verify that the configuration is working correctly Requirements: -- Provide specific operation methods for each step -- If I encounter an error, help me analyze the cause and provide a solution -- After completing each step, ask me if it was successful, and then proceed to the next step +- Provide specific instructions for each step +- If I encounter problems, help me analyze the cause and provide solutions +- After completing each step, ask me if it was successful before continuing to the next step Now, let's start with the first step. ``` @@ -64,20 +66,20 @@ Now, let's start with the first step. ### 🍎 macOS Users ``` -You are a patient VS Code configuration assistant. I am using a macOS system, and now I need you to guide me step by step to configure VS Code. +You are a patient VS Code configuration assistant. I am using a macOS system, and now I need you to guide me step-by-step to configure VS Code. -Please guide me in the following order, giving me one step at a time, and wait for my confirmation before proceeding to the next step: +Please guide me in the following order, giving me only one step at a time, and waiting for my confirmation before proceeding to the next: 1. Install VS Code (via Homebrew or official website) -2. Configure the 'code' command-line tool -3. Install basic development extensions (GitLens, Prettier, ESLint, Local History) +2. Configure the `code` command-line tool +3. Install essential development extensions (GitLens, Prettier, ESLint, Local History) 4. Configure auto-save and formatting 5. Verify that the configuration is working correctly Requirements: -- Provide specific operation methods for each step -- If I encounter an error, help me analyze the cause and provide a solution -- After completing each step, ask me if it was successful, and then proceed to the next step +- Provide specific instructions for each step +- If I encounter problems, help me analyze the cause and provide solutions +- After completing each step, ask me if it was successful before continuing to the next step Now, let's start with the first step. ``` @@ -85,20 +87,20 @@ Now, let's start with the first step. ### 🐧 Linux Users ``` -You are a patient VS Code configuration assistant. I am using a Linux system (Ubuntu/Debian), and now I need you to guide me step by step to configure VS Code. +You are a patient VS Code configuration assistant. I am using a Linux system (Ubuntu/Debian), and now I need you to guide me step-by-step to configure VS Code. -Please guide me in the following order, giving me one step at a time, and wait for my confirmation before proceeding to the next step: +Please guide me in the following order, giving me only one step at a time, and waiting for my confirmation before proceeding to the next: 1. Install VS Code (via apt or snap) -2. Install basic development extensions (GitLens, Prettier, ESLint, Local History) +2. Install essential development extensions (GitLens, Prettier, ESLint, Local History) 3. Configure auto-save and formatting 4. Configure terminal integration 5. Verify that the configuration is working correctly Requirements: -- Provide specific operation methods for each step -- If I encounter an error, help me analyze the cause and provide a solution -- After completing each step, ask me if it was successful, and then proceed to the next step +- Provide specific instructions for each step +- If I encounter problems, help me analyze the cause and provide solutions +- After completing each step, ask me if it was successful before continuing to the next step Now, let's start with the first step. ``` @@ -110,28 +112,28 @@ Now, let's start with the first step. > AI-native IDE, based on VS Code, with built-in AI programming features. Official website: https://cursor.com ``` -You are a patient Cursor IDE configuration assistant. I want to use Cursor as my main development tool, and I need you to guide me step by step through the installation and configuration. +You are a patient Cursor IDE configuration assistant. I want to use Cursor as my primary development tool, and I need you to guide me step-by-step through the installation and configuration. My operating system is: [Please tell me if you are using Windows/macOS/Linux] -Please guide me in the following order, giving me one step at a time, and wait for my confirmation before proceeding to the next step: +Please guide me in the following order, giving me only one step at a time, and waiting for my confirmation before proceeding to the next: -1. Download and install Cursor (official website: https://cursor.com) -2. First-time startup configuration (login, theme selection, etc.) +1. Download and install Cursor (Official website: https://cursor.com) +2. Initial startup configuration (login, select theme, etc.) 3. Import VS Code settings and extensions (if you have used VS Code before) 4. Configure AI features (API Key or subscription) 5. Learn Cursor's core shortcuts: - Cmd/Ctrl + K: AI Edit - Cmd/Ctrl + L: AI Chat - - Cmd/Ctrl + I: Composer mode + - Cmd/Ctrl + I: Composer Mode 6. Configure auto-save 7. Verify that AI features are working correctly Requirements: -- Provide specific operation methods for each step +- Provide specific instructions for each step - Explain Cursor's unique features compared to VS Code -- If I encounter an error, help me analyze the cause and provide a solution -- After completing each step, ask me if it was successful, and then proceed to the next step +- If I encounter problems, help me analyze the cause and provide solutions +- After completing each step, ask me if it was successful before continuing to the next step Now, first ask me what operating system I am using. ``` @@ -140,27 +142,27 @@ Now, first ask me what operating system I am using. ## Windsurf -> AI-native IDE, free tier for new users. Official website: https://windsurf.com +> AI-native IDE, new users get free credits. Official website: https://windsurf.com ``` -You are a patient Windsurf IDE configuration assistant. I want to use Windsurf as my development tool, and I need you to guide me step by step through the installation and configuration. +You are a patient Windsurf IDE configuration assistant. I want to use Windsurf as my development tool, and I need you to guide me step-by-step through the installation and configuration. My operating system is: [Please tell me if you are using Windows/macOS/Linux] -Please guide me in the following order, giving me one step at a time, and wait for my confirmation before proceeding to the next step: +Please guide me in the following order, giving me only one step at a time, and waiting for my confirmation before proceeding to the next: -1. Download and install Windsurf (official website: https://windsurf.com) -2. Register an account and log in (new users get a free tier) -3. First-time startup configuration +1. Download and install Windsurf (Official website: https://windsurf.com) +2. Register an account and log in (new users get free credits) +3. Initial startup configuration 4. Understand Windsurf's AI features (Cascade, etc.) 5. Configure the basic development environment 6. Verify that AI features are working correctly Requirements: -- Provide specific operation methods for each step +- Provide specific instructions for each step - Explain Windsurf's unique features -- If I encounter an error, help me analyze the cause and provide a solution -- After completing each step, ask me if it was successful, and then proceed to the next step +- If I encounter problems, help me analyze the cause and provide solutions +- After completing each step, ask me if it was successful before continuing to the next step Now, first ask me what operating system I am using. ``` @@ -169,4 +171,4 @@ Now, first ask me what operating system I am using. ## After Configuration -After IDE configuration is complete, read [README.md](../../../../README.md) to understand the Vibe Coding workflow and start your first project! +Once your IDE is configured, read [README.md](../../../../README.md) to understand the Vibe Coding workflow and start your first project! diff --git a/i18n/en/documents/01-getting-started/README.md b/i18n/en/documents/01-getting-started/README.md index 57bb678..b03a3c3 100644 --- a/i18n/en/documents/01-getting-started/README.md +++ b/i18n/en/documents/01-getting-started/README.md @@ -1,29 +1,17 @@ -# 🚀 Starting Vibe Coding from Scratch +```markdown +# 🚀 Getting Started Guide -> Absolutely no foundation? Follow the steps below in order to start your AI programming journey. +> Learn Vibe Coding from scratch, configure your environment ---- +## 📚 Learning Path -## Learning Path +1. [Vibe Coding Philosophical Principles](./00-Vibe%20Coding%20哲学原理.md) - Understanding Core Concepts +2. [Network Environment Configuration](./01-网络环境配置.md) - Configuring Network Access +3. [Development Environment Setup](./02-开发环境搭建.md) - Setting up the Development Environment +4. [IDE Configuration](./03-IDE配置.md) - Configuring your Editor -| No. | Document | Description | -|:---:|:---|:---| -| 00 | [Philosophy](./00-Vibe%20Coding%20Philosophy.md) | Understand the core concepts of Vibe Coding | -| 01 | [Network Environment Configuration](./01-Network%20Environment%20Configuration.md) | Configure network to ensure access to GitHub, Google, etc. | -| 02 | [Development Environment Setup](./02-Development%20Environment%20Setup.md) | Copy prompts to AI, let AI guide you to install development tools | -| 03 | [IDE Configuration](./03-IDE%20Configuration.md) | Configure VS Code editor | - ---- - -## How to use - -1. Read each document in order -2. Prompts in the document can be directly copied to an AI chat box (ChatGPT, Claude, Gemini web version) -3. AI will guide you step by step to complete the configuration -4. Ask AI directly if you encounter problems - ---- - -## After completion - -After all configurations are complete, read the [Main Document](../../../../README.md) to understand the Vibe Coding workflow. +## 🔗 Related Resources +- [Basic Guide](../00-基础指南/) - Core Concepts and Methodology +- [Methodology](../02-方法论/) - Tools and Experience +- [Practice](../03-实战/) - Hands-on Projects +``` diff --git a/i18n/en/documents/02-methodology/README.md b/i18n/en/documents/02-methodology/README.md index 38ceb8d..11935a5 100644 --- a/i18n/en/documents/02-methodology/README.md +++ b/i18n/en/documents/02-methodology/README.md @@ -1,12 +1,21 @@ -# 02-Methodology +# 🛠️ Methodology -Tools, tutorials, and development guides. +> Tool Usage, Development Experience, and Practical Skills -## Contents +## 📖 Tool Tutorials -- [tmux Shortcut Cheatsheet](./tmux%20Shortcut%20Cheatsheet.md) -- [LazyVim Shortcut Cheatsheet](./LazyVim%20Shortcut%20Cheatsheet.md) -- [auggie-mcp Configuration Document](./auggie-mcp%20Configuration%20Document.md) -- [SSH via Mobile with FRP](./How%20to%20SSH%20to%20Local%20Computer%20from%20Any%20Location%20via%20Mobile%2C%20Based%20on%20FRP%20Implementation.md) -- [Gemini Headless Mode Translation Guide](./Gemini%20Headless%20Mode%20Translation%20Guide.md) -- [Vibe Coding Experience Collection](./vibe-coding-experience-collection.md) +- [tmux Shortcut Cheatsheet](./tmux快捷键大全.md) - Terminal Multiplexer +- [LazyVim Shortcut Cheatsheet](./LazyVim快捷键大全.md) - Neovim Configuration Framework +- [Augment MCP Configuration](./auggie-mcp配置文档.md) - Context Engine Configuration +- [Remote Vibe Coding via Mobile](./关于手机ssh任意位置链接本地计算机，基于frp实现的方法.md) - Remote Development based on frp +- [GEMINI-HEADLESS](./GEMINI-HEADLESS.md) - Gemini Headless Mode Configuration + +## 🛠️ Development Experience + +- [Development Experience](./开发经验.md) - Variable Naming, File Structure, Coding Standards +- [Vibe Coding Experience Collection](./vibe-coding-经验收集.md) - Community Experience Summary + +## 🔗 Related Resources +- [Basic Guide](../00-基础指南/) - Core Concepts and Methodology +- [Getting Started Guide](../01-入门指南/) - From Zero to Hero +- [Practice](../03-实战/) - Hands-on Practice diff --git a/i18n/en/documents/03-practice/README.md b/i18n/en/documents/03-practice/README.md index 8307fd8..1ceb833 100644 --- a/i18n/en/documents/03-practice/README.md +++ b/i18n/en/documents/03-practice/README.md @@ -1,26 +1,17 @@ -# 📁 Project Practical Experience +# 🎯 Hands-on Practice -> Experiences, pitfall records, and reusable prompts accumulated during Vibe Coding practical applications. +> Real-world project development experience and review ---- +## 🏗️ Project Practice Experience -## 📂 Directory Index +| Project | Description | +|:---|:---| +| [polymarket-dev](./polymarket-dev/) | Polymarket Data Analysis | +| [telegram-dev](./telegram-dev/) | Telegram Bot Development | +| [web-app](./web-app/) | Web Application Development | -| Directory | Description | Status | -|:---|:---|:---:| -| [fate-engine-dev](./fate-engine-dev/) | Fate Engine Development - Bazi calculation, True Solar Time correction | ✅ | -| [polymarket-dev](./polymarket-dev/) | Polymarket Data Analysis - Candlestick chart visualization, glue development | ✅ | -| [telegram-dev](./telegram-dev/) | Telegram Bot Development - Markdown format processing | ✅ | -| [web-app](./web-app/) | Full-stack Web Application Case Study | 🚧 | -| [cli-tool](./cli-tool/) | CLI Tool Development Case Study | 🚧 | -| [bot-automation](./bot-automation/) | Automation Bot Case Study | 🚧 | -| [data-pipeline](./data-pipeline/) | Data Processing Pipeline Case Study | 🚧 | -| [game-dev](./game-dev/) | Game Development Case Study | 🚧 | - ---- - -## 📝 How to Contribute - -Welcome to submit your practical experiences! Suggested format: -- Filename: `ProjectName_ProblemDescription_Date.md` or `FeatureName-prompt.md` -- Content includes: Background, problem, solution, reusable prompts +## 🔗 Related Resources +- [Fundamentals Guide](../00-fundamentals/) - Core concepts and methodologies +- [Getting Started Guide](../01-getting-started/) - Environment setup +- [Methodology](../02-methodology/) - Tools and experience +- [Resources](../04-resources/) - Templates and tools diff --git a/i18n/en/documents/03-practice/fate-engine-dev/prompt-system-bazi-kline.md b/i18n/en/documents/03-practice/fate-engine-dev/prompt-system-bazi-kline.md new file mode 100644 index 0000000..543a335 --- /dev/null +++ b/i18n/en/documents/03-practice/fate-engine-dev/prompt-system-bazi-kline.md @@ -0,0 +1,48 @@ +Here is the English translation: + +# Life K-Line LLM System Prompt (Full Text) + +The following content corresponds to the `BAZI_SYSTEM_INSTRUCTION` string in `libs/external/web/lifekline-main/constants.ts`, expanded as is for easy viewing and reuse. + +``` +你是一位八字命理大师，精通加密货币市场周期。根据用户提供的四柱干支和大运信息，生成"人生K线图"数据和命理报告。 + +**核心规则:** +1. **年龄计算**: 采用虚岁，从 1 岁开始。 +2. **K线详批**: 每年每月的 `reason` 字段必须**控制在40-60字以内**，简洁描述吉凶趋势即可。 +3. **评分机制**: 所有维度给出 0-10 分。 +4. **数据起伏**: 让评分根据真实的测算波动 + +**输出JSON结构:** + +{ + "bazi": ["年柱", "月柱", "日柱", "时柱"], + "summary": "命理总评（100字）", + "summaryScore": 8, + "personality": "性格分析（80字）", + "personalityScore": 8, + "industry": "事业分析（80字）", + "industryScore": 7, + "fengShui": "风水建议：方位、地理环境、开运建议（80字）", + "fengShuiScore": 8, + "wealth": "财富分析（80字）", + "wealthScore": 9, + "marriage": "婚姻分析（80字）", + "marriageScore": 6, + "health": "健康分析（60字）", + "healthScore": 5, + "family": "六亲分析（60字）", + "familyScore": 7, + "crypto": "币圈分析（60字）", + "cryptoScore": 8, + "chartPoints": [ + {"age":1,"year":1990,"daYun":"童限","ganZhi":"庚午","open":50,"close":55,"high":60,"low":45,"score":55,"reason":"开局平稳，家庭呵护"}, + ... (共x条（x = 全部流月数量），reason控制在40-60字) + ] +} + +``` + +# Usage Instructions +- Pass as a `system` message to `/chat/completions`. The model is prohibited from outputting Markdown code blocks (as re-emphasized by `geminiService`). +- Ensure there are `x` entries (`x = total number of monthly flows`) in `chartPoints`, and strictly adhere to the `reason` character limit and score fluctuation requirements. diff --git a/i18n/en/documents/03-practice/fate-engine-dev/prompt-user-bazi-kline.md b/i18n/en/documents/03-practice/fate-engine-dev/prompt-user-bazi-kline.md new file mode 100644 index 0000000..a3a319c --- /dev/null +++ b/i18n/en/documents/03-practice/fate-engine-dev/prompt-user-bazi-kline.md @@ -0,0 +1,55 @@ +Here is the English translation of the provided text: + +# Life Chart LLM User Prompt Template (Full Original Text) + +This document is extracted from the `userPrompt` assembly logic in `libs/external/web/lifekline-main/services/geminiService.ts`, and has been replaced with template variables for direct reuse. + +``` +请根据以下**已经排好的**八字四柱和**指定的大运信息**进行分析。 + +【基本信息】 +性别：${genderStr} +姓名：${input.name || "未提供"} +出生年份：${input.birthYear}年 (阳历) + +【八字四柱】 +年柱：${input.yearPillar} (天干属性：${yearStemPolarity === 'YANG' ? '阳' : '阴'}) +月柱：${input.monthPillar} +日柱：${input.dayPillar} +时柱：${input.hourPillar} + +【大运核心参数】 +1. 起运年龄：${input.startAge} 岁 (虚岁)。 +2. 第一步大运：${input.firstDaYun}。 +3. **排序方向**：${daYunDirectionStr}。 + +【必须执行的算法 - 大运序列生成】 +请严格按照以下步骤生成数据： + +1. **锁定第一步**：确认【${input.firstDaYun}】为第一步大运。 +2. **计算序列**：根据六十甲子顺序和方向（${daYunDirectionStr}），推算出接下来的 9 步大运。 + ${directionExample} +3. **填充 JSON**： + - Age 1 到 ${startAgeInt - 1}: daYun = "童限" + - Age ${startAgeInt} 到 ${startAgeInt + 9}: daYun = [第1步大运: ${input.firstDaYun}] + - Age ${startAgeInt + 10} 到 ${startAgeInt + 19}: daYun = [第2步大运] + - Age ${startAgeInt + 20} 到 ${startAgeInt + 29}: daYun = [第3步大运] + - ...以此类推直到 100 岁。 + +【特别警告】 +- **daYun 字段**：必须填大运干支（10年一变），**绝对不要**填流年干支。 +- **ganZhi 字段**：填入该年份的**流年干支**（每年一变，例如 2024=甲辰，2025=乙巳）。 + +任务： +1. 确认格局与喜忌。 +2. 生成 **1-100 岁 (虚岁)** 的人生流年K线数据。 +3. 在 `reason` 字段中提供流年详批。 +4. 生成带评分的命理分析报告（包含性格分析、币圈交易分析、发展风水分析）。 + +请严格按照系统指令生成 JSON 数据。 +``` + +# Instructions for Use +- Pass as a `user` message to `/chat/completions`, to be used in conjunction with the system prompt. +- Variable meanings: `genderStr` consists of gender + Qian-Kun text; `startAgeInt` is the integer start age; `directionExample` changes with forward/reverse order; other variables are directly taken from user input or the Bazi plotting results. +- The output must be pure JSON, and `geminiService` will automatically strip code blocks and validate `chartPoints`. diff --git a/i18n/en/documents/04-resources/External Resource Aggregation.md b/i18n/en/documents/04-resources/External Resource Aggregation.md index 166d6d4..87ecad5 100644 --- a/i18n/en/documents/04-resources/External Resource Aggregation.md +++ b/i18n/en/documents/04-resources/External Resource Aggregation.md @@ -1,532 +1,789 @@ -# 🔗 External Resource Aggregation +Here is the translated content of the `README.md` file: -> Summary of high-quality external resources related to Vibe Coding -> -> Last updated: 2025-12-19 +```markdown + +

+ + Vibe Coding Guide +

+ +
+ +# Vibe Coding Guide + +**The ultimate workstation to turn ideas into reality through AI pair programming** + +--- + + + +

+ License + Main Language + Code Size + X + Chat Group +

+ + +

+ Simplified Chinese + English + More Languages +

+ + + +

+ Core Philosophy + Glue Coding + From Scratch + Language Layer Elements + Common Pitfalls + Hard Constraints + Aggregated Information Sources + Meta-Methodology + The Art of Programming + Case Studies + Toolchain + Curated Prompts + Skills All Skills + Prompts Online Table + System Prompts Repo + Chat Vault +

+ +[📋 Tools & Resources](#-器-工具与资源) +[🚀 Get Started](#-从零开始) +[🎯 Original Repo Translation](#-原仓库翻译) +[⚙️ Full Setup Process](#️-完整设置流程) +[📞 Contact Info](#-联系方式) +[✨ Support Project](#-支持项目) +[🤝 Contribute](#-参与贡献) + +AI interpretation link for this repository: [zread.ai/tukuaiai/vibe-coding-cn](https://zread.ai/tukuaiai/vibe-coding-cn/1-overview) + +
+ +## 🎲 Foreword + +**This is a constantly growing and self-negating project. All current experience and capabilities may become meaningless due to the evolution of AI capabilities. Therefore, please always maintain an AI-first mindset, do not be complacent, all experience may become invalid, view it dialectically🙏🙏🙏** + +--- + +
+⚡ 5 Minute Quickstart + +## ⚡ 5 Minute Quickstart + +> Already have an internet and development environment? Start Vibe Coding directly! + +**Step 1**: Copy the prompt below and paste it into [Claude](https://claude.ai/) or [ChatGPT](https://chatgpt.com/) + +``` +You are a professional AI programming assistant. I want to develop a project using Vibe Coding. + +Please ask me first: +1. What project do you want to work on? (Describe in one sentence) +2. What programming languages are you familiar with? (No worries if you're not familiar) +3. What is your operating system? + +Then help me: +1. Recommend the simplest tech stack +2. Generate the project structure +3. Guide me step-by-step through the development + +Requirement: After each step is completed, ask me if it was successful before continuing to the next step. +``` + +**Step 2**: Follow the AI's guidance to turn your ideas into reality 🚀 + +**It's that simple!** For more advanced content, continue reading 👇 + +
+ +--- + +## 🚀 Get Started + +Completely new? Follow these steps in order: + +0. [00-Vibe Coding Philosophical Principles](./i18n/zh/documents/01-入门指南/00-Vibe%20Coding%20哲学原理.md) - Understand the core concepts +1. [01-Network Environment Configuration](./i18n/zh/documents/01-入门指南/01-网络环境配置.md) - Configure network access +2. [02-Development Environment Setup](./i18n/zh/documents/01-入门指南/02-开发环境搭建.md) - Copy the prompt to AI and let AI guide you through setting up the environment +3. [03-IDE Configuration](./i18n/zh/documents/01-入门指南/03-IDE配置.md) - Configure VS Code editor ---
-🎙️ Quality Bloggers +🧬 Glue Coding -### 𝕏 (Twitter) Bloggers +> **The Holy Grail and Silver Bullet of Software Engineering** -| Blogger | Link | Description | -|:---|:---|:---| -| @shao__meng | [x.com/shao__meng](https://x.com/shao__meng) | | -| @0XBard_thomas | [x.com/0XBard_thomas](https://x.com/0XBard_thomas) | | -| @Pluvio9yte | [x.com/Pluvio9yte](https://x.com/Pluvio9yte) | | -| @xDinoDeer | [x.com/xDinoDeer](https://x.com/xDinoDeer) | | -| @geekbb | [x.com/geekbb](https://x.com/geekbb) | | -| @GitHub_Daily | [x.com/GitHub_Daily](https://x.com/GitHub_Daily) | | -| @BiteyeCN | [x.com/BiteyeCN](https://x.com/BiteyeCN) | | -| @CryptoJHK | [x.com/CryptoJHK](https://x.com/CryptoJHK) | | -| @rohanpaul_ai | [x.com/rohanpaul_ai](https://x.com/rohanpaul_ai) | | -| @DataChaz | [x.com/DataChaz](https://x.com/DataChaz) | | +Glue coding is the ultimate evolved form of Vibe Coding, potentially perfectly solving three fatal flaws: -### 📺 YouTube Bloggers - -| Blogger | Link | Description | -|:---|:---|:---| -| Best Partners | [youtube.com/ @bestpartners](https://www.youtube.com/ @bestpartners) | | -| 王路飞 | [youtube.com/ @王路飞](https://www.youtube.com/ @%E7%8E%8B%E8%B7%AF%E9%A3%9E) | | -| 即刻风 | [youtube.com/ @jidifeng](https://www.youtube.com/ @jidifeng) | | -| 3Blue1Brown | [youtube.com/ @3blue1brown](https://www.youtube.com/ @3blue1brown) | Math visualization | -| Andrej Karpathy | [youtube.com/andrejkarpathy](https://www.youtube.com/andrejkarpathy) | AI/Deep Learning | - -### 📱 WeChat Video Accounts - -| Blogger | Description | +| Problem | Solution | |:---|:---| -| 美国的牛粪博士 | | +| 🎭 AI Hallucinations | ✅ Only use validated mature code, zero hallucinations | +| 🧩 Complexity Explosion | ✅ Each module is a battle-tested wheel | +| 🎓 High Barrier to Entry | ✅ You only need to describe the "connection method" | -### 🎵 Douyin +**Core Concept**: Copy, don't write. Connect, don't build. Reuse, don't originate. -| Blogger | Description | -|:---|:---| +👉 [Learn more about Glue Coding](./i18n/zh/documents/00-基础指南/胶水编程.md)
--- +## 🖼️ Overview + +**Vibe Coding** is the ultimate AI pair programming workflow designed to help developers smoothly turn ideas into reality. This guide details the entire process from project conception, tech stack selection, implementation planning to specific development, debugging, and expansion, emphasizing **plan-driven** and **modularization** as the core to prevent AI from losing control and causing project chaos. + +> **Core Concept**: *Planning is everything.* Be cautious about letting AI plan autonomously, otherwise your codebase will turn into an unmanageable mess. + +**Note**: The experiences shared below are not universally applicable. Please integrate them dialectically with specific scenarios in your practice. +
-🤖 AI Tools and Platforms +🔑 Meta-Methodology -### 💬 AI Chat Platforms -#### Tier 1 (Recommended) +The core of this idea is to build an AI system capable of **self-optimization**. Its recursive nature can be broken down into the following steps: -| Platform | Model | Features | -|:---|:---|:---| -| [Claude](https://claude.ai/) | Claude Opus 4.5 | Strong coding capabilities, supports Artifacts | -| [ChatGPT](https://chatgpt.com/) | GPT-5.1 | Strong comprehensive capabilities, supports Codex | -| [Gemini](https://gemini.google.com/) | Gemini 3.0 Pro | Large free quota, supports long context | +> Further reading: [A Formalization of Recursive Self-Optimizing Generative Systems](./i18n/zh/documents/00-基础指南/A%20Formalization%20of%20Recursive%20Self-Optimizing%20Generative%20Systems.md) -#### Domestic Platforms +#### 1. Define Core Roles: -| Platform | Model | Features | -|:---|:---|:---| -| [Kimi](https://kimi.moonshot.cn/) | Kimi K2 | Strong long-text processing | -| [Tongyi Qianwen](https://tongyi.aliyun.com/) | Qwen | Developed by Alibaba, free | -| [Zhipu Qingyan](https://chatglm.cn/) | GLM-4 | Developed by Zhipu AI | -| [Doubao](https://www.doubao.com/) | Doubao | Developed by ByteDance | +* **α-Prompt (Generator)**: A "mother" prompt whose sole responsibility is to **generate** other prompts or skills. +* **Ω-Prompt (Optimizer)**: Another "mother" prompt whose sole responsibility is to **optimize** other prompts or skills. -### 🖥️ AI Programming IDEs +#### 2. Describe the Recursive Lifecycle: -| Tool | Link | Description | -|:---|:---|:---| -| Cursor | [cursor.com](https://cursor.com/) | AI-native editor, based on VS Code | -| Windsurf | [windsurf.com](https://windsurf.com/) | From Codeium | -| Kiro | [kiro.dev](https://kiro.dev/) | From AWS, free Claude Opus | -| Zed | [zed.dev](https://zed.dev/) | High-performance editor, supports AI | +1. **Bootstrap**: + * Use AI to generate initial versions (v1) of `α-Prompt` and `Ω-Prompt`. -### ⌨️ AI CLI Tools +2. **Self-Correction & Evolution**: + * Use `Ω-Prompt (v1)` to **optimize** `α-Prompt (v1)`, resulting in a more powerful `α-Prompt (v2)`. -| Tool | Command | Description | -|:---|:---|:---| -| Claude Code | `claude` | Anthropic official CLI | -| Codex CLI | `codex` | OpenAI official CLI | -| Gemini CLI | `gemini` | Google official CLI, 1000 free uses/day | -| Aider | `aider` | Open-source AI pair programming, Git integration | -| OpenCode | `opencode` | Open-source terminal AI assistant, written in Go | -| Cline CLI | `cline` | VS Code extension companion CLI | +3. **Generation**: + * Use the **evolved** `α-Prompt (v2)` to generate all required target prompts and skills. -### 🤖 AI Agent Platforms +4. **Recursive Loop**: + * Feed the newly generated, more powerful artifacts (including new versions of `Ω-Prompt`) back into the system, restarting the continuous evolution to optimize `α-Prompt`. -| Tool | Link | Description | -|:---|:---|:---| -| Devin | [devin.ai](https://devin.ai/) | Autonomous AI software engineer, $20/month | -| Replit Agent | [replit.com](https://replit.com/) | End-to-end application building Agent | -| v0 by Vercel | [v0.dev](https://v0.dev/) | AI UI generation, React + Tailwind | -| Bolt.new | [bolt.new](https://bolt.new/) | In-browser full-stack application building | -| Lovable | [lovable.dev](https://lovable.dev/) | Formerly GPT Engineer, natural language app building | +#### 3. Ultimate Goal: -### 🆓 Free Resources - -#### Completely Free - -| Resource | Link | Description | -|:---|:---|:---| -| AI Studio | [aistudio.google.com](https://aistudio.google.com/) | Google free Gemini | -| Gemini CLI | [geminicli.com](https://geminicli.com/) | Free command line access | -| antigravity | [antigravity.google](https://antigravity.google/) | Google free AI service | -| Qwen CLI | [qwenlm.github.io](https://qwenlm.github.io/qwen-code-docs/zh/cli/) | Alibaba free CLI | - -#### With Free Quotas - -| Resource | Link | Description | -|:---|:---|:---| -| Kiro | [kiro.dev](https://kiro.dev/) | Free Claude Opus 4.5 | -| Windsurf | [windsurf.com](https://windsurf.com/) | Free quota for new users | -| GitHub Copilot | [github.com/copilot](https://github.com/copilot) | Free for students/open source | -| Codeium | [codeium.com](https://codeium.com/) | Free AI code completion | -| Tabnine | [tabnine.com](https://www.tabnine.com/) | Free basic version | -| Continue | [continue.dev](https://continue.dev/) | Open-source AI code assistant | -| Bito | [bito.ai](https://bito.ai/) | Free AI code assistant | - -### 🎨 AI Generation Tools - -| Type | Tool | Link | -|:---|:---|:---| -| Image | Midjourney | [midjourney.com](https://midjourney.com/) | -| Image | DALL-E 3 | [ChatGPT](https://chatgpt.com/) | -| Image | Ideogram | [ideogram.ai](https://ideogram.ai/) | -| Image | Leonardo AI | [leonardo.ai](https://leonardo.ai/) | -| Music | Suno | [suno.ai](https://suno.ai/) | -| Music | Udio | [udio.com](https://www.udio.com/) | -| Sound Effects | ElevenLabs | [elevenlabs.io](https://elevenlabs.io/) | -| Video | Sora | [sora.com](https://sora.com/) | -| Video | Runway | [runwayml.com](https://runwayml.com/) | -| Video | Kling | [klingai.com](https://klingai.com/) | -| 3D | Meshy | [meshy.ai](https://www.meshy.ai/) | +Through this continuous **recursive optimization loop**, the system achieves **self-transcendence** in each iteration, infinitely approaching the preset **desired state**.
+
+🧭 Methodology Essentials (Dao · Fa · Shu) + +## 🧭 Dao (The Way) + +* **If AI can do it, don't do it manually** +* **Ask AI about everything** +* **Purpose-driven: All actions in the development process revolve around the "purpose"** +* **Context is the first principle of vibe coding; garbage in, garbage out** +* **Systematic thinking, entities, links, functions/purposes, three dimensions** +* **Data and functions are everything in programming** +* **Input, process, output describe the entire process** +* **Ask AI "what?", "why?", "how to do it?" (Golden Circle Rule)** +* **Structure first, then code. Always plan the framework well, otherwise you'll be endlessly paying technical debt** +* **Occam's Razor, don't add code if unnecessary** +* **Pareto Principle, focus on the important 20%** +* **Reverse thinking, first clarify your requirements, then build code backward from requirements** +* **Repeat, try multiple times. If it still doesn't work, open a new window.** +* **Focus, extreme focus can penetrate code. Do one thing at a time (except for divine beings)** + + +## 🧩 Fa (The Method) + +* **One-sentence goal + non-goals** +* **Orthogonality (context-dependent)** +* **Copy, don't write. Don't reinvent the wheel. First ask AI if there's a suitable repository, download and modify it (a new paradigm for glue coding)** +* **Always read the official documentation. First scrape the official documentation and feed it to AI (let AI find tools to download locally)** +* **Decompose modules by responsibility** +* **Interface first, implementation later** +* **Modify only one module at a time** +* **Documentation is context, not an afterthought** + +## 🛠️ Shu (The Technique) + +* Clearly state: **what can be modified, what cannot be modified** +* For Debugging, only provide: **expected vs actual + minimal reproduction** +* Testing can be handed over to AI, **assertions are human-reviewed** +* When there's too much code, **switch sessions** +* **Consolidate AI-made errors into persistent experience using prompts. If a problem remains unsolved, let AI retrieve this collection of problems and find a solution.** + +
+ +
+📋 Tools & Resources + +## 📋 Tools & Resources + +### Integrated Development Environment (IDE) & Terminal + +* [**Visual Studio Code**](https://code.visualstudio.com/): A powerful integrated development environment, suitable for code reading and manual modifications. Its `Local History` plugin is particularly convenient for project version management. +* **Virtual Environment (.venv)**: Highly recommended, allows one-click configuration and isolation of project environments, especially suitable for Python development. +* [**Cursor**](https://cursor.com/): Has captured users' minds and is widely known. +* [**Warp**](https://www.warp.dev/): A modern terminal integrated with AI features, which can effectively improve the efficiency of command-line operations and error troubleshooting. +* [**Neovim (nvim)**](https://github.com/neovim/neovim): A high-performance modern Vim editor with a rich plugin ecosystem, the first choice for keyboard-driven developers. +* [**LazyVim**](https://github.com/LazyVim/LazyVim): A Neovim configuration framework that comes with a full suite of features such as LSP, code completion, and debugging, achieving a balance between out-of-the-box usability and deep customization. + +### AI Models & Services + +* [**Claude Opus 4.5**](https://claude.ai/new): A powerful AI model, providing services through platforms like Claude Code, and supporting CLI and IDE plugins. +* [**gpt-5.1-codex.1-codex (xhigh)**](https://chatgpt.com/codex/): An AI model suitable for handling large projects and complex logic, available through platforms like Codex CLI. +* [**Droid**](https://factory.ai/news/terminal-bench): Provides CLI access to various models including Claude Opus 4.5. +* [**Kiro**](https://kiro.dev/): Currently provides free Claude Opus 4.5 model access and offers client and CLI tools. +* [**Gemini CLI**](https://geminicli.com/): Provides free access to the Gemini model, suitable for executing scripts, organizing documents, and exploring ideas. +* [**antigravity**](https://antigravity.google/): Currently a free AI service provided by Google, supporting Claude Opus 4.5 and Gemini 3.0 Pro. +* [**AI Studio**](https://aistudio.google.com/prompts/new_chat): A free service provided by Google, supporting Gemini 3.0 Pro and Nano Banana. +* [**Gemini Enterprise**](https://cloud.google.com/gemini-enterprise): Google AI service for enterprise users, currently free to use. +* [**GitHub Copilot**](https://github.com/copilot): An AI code completion tool developed jointly by GitHub and OpenAI. +* [**Kimi K2**](https://www.kimi.com/): A domestic AI model suitable for various general tasks. +* [**GLM**](https://bigmodel.cn/): A domestic large language model developed by Zhipu AI. +* [**Qwen**](https://qwenlm.github.io/qwen-code-docs/zh/cli/): An AI model developed by Alibaba, its CLI tool offers free usage quota. + +### Development & Auxiliary Tools + +* [**Augment**](https://app.augmentcode.com/): Provides powerful context engine and prompt optimization features. +* [**Windsurf**](https://windsurf.com/): An AI development tool offering free credits for new users. +* [**Ollama**](https://ollama.com/): A local large model management tool, allowing convenient pulling and running of open-source models via the command line. +* [**Mermaid Chart**](https://www.mermaidchart.com/): Used to convert text descriptions into architectural diagrams, sequence diagrams, and other visual charts. +* [**NotebookLM**](https://notebooklm.google.com/): A tool for AI to interpret materials, audio, and generate mind maps. +* [**Zread**](https://zread.ai/): An AI-driven GitHub repository reading tool that helps quickly understand project code. +* [**tmux**](https://github.com/tmux/tmux): A powerful terminal multiplexer, supporting session persistence, split panes, and background tasks, ideal for server and multi-project development. +* [**DBeaver**](https://dbeaver.io/): A universal database management client, supporting various databases with comprehensive features. + +### Resources & Templates + +* [**Prompt Library (Online Table)**](https://docs.google.com/spreadsheets/d/1ngoQOhJqdguwNAilCl1joNwTje7FWWN9WiI2bo5VhpU/edit?gid=2093180351#gid=2093180351&range=A1): An online table containing a large number of ready-to-use prompts of various types. +* [**Third-party System Prompt Learning Library**](https://github.com/x1xhlol/system-prompts-and-models-of-ai-tools): For learning and referencing system prompts of other AI tools. +* [**Skills Creator**](https://github.com/yusufkaraaslan/Skill_Seekers): A tool that can generate customized Skills according to demand. +* [**Meta Prompts**](https://docs.google.com/spreadsheets/d/1ngoQOhJqdguwNAilCl1joNwTje7FWWN9WiI2bo5VhpU/edit?gid=1770874220#gid=1770874220): Advanced prompts for generating prompts. +* [**General Project Architecture Template**](./i18n/zh/documents/00-基础指南/通用项目架构模板.md): Can be used to quickly set up standardized project directory structures. +* [**Meta-Skill: Skills of Skills**](./i18n/zh/skills/00-元技能/claude-skills/SKILL.md): Meta-skill for generating Skills. +* [**tmux Shortcut Cheatsheet**](./i18n/zh/documents/02-方法论/tmux快捷键大全.md): tmux shortcut reference document. +* [**LazyVim Shortcut Cheatsheet**](./i18n/zh/documents/02-方法论/LazyVim快捷键大全.md): LazyVim shortcut reference document. +* [**Mobile Remote Vibe Coding**](./i18n/zh/documents/02-方法论/关于手机ssh任意位置链接本地计算机，基于frp实现的方法.md): Achieve mobile SSH remote control of local computers for Vibe Coding based on frp. + +### External Tutorials & Resources + +* [**Brother Er's Java Advanced Path**](https://javabetter.cn/): Contains detailed configuration tutorials for various development tools. +* [**Virtual Card**](https://www.bybit.com/cards/?ref=YDGAVPN&source=applet_invite): Can be used to register cloud services and other international payment scenarios. + +### Community & Communication + +* [**Telegram Chat Group**](https://t.me/glue_coding): Vibe Coding Chinese communication group +* [**Telegram Channel**](https://t.me/tradecat_ai_channel): Project updates and information + +### Internal Project Documentation + +* [**Glue Coding**](./i18n/zh/documents/00-基础指南/胶水编程.md): The holy grail and silver bullet of software engineering, the ultimate evolution of Vibe Coding. +* [**Chat Vault**](./libs/external/chat-vault/README_CN.md): AI chat log saving tool, supporting Codex/Kiro/Gemini/Claude CLI. +* [**prompts-library Tool Description**](./libs/external/prompts-library/README_CN.md): Supports Excel and Markdown format conversion, including hundreds of curated prompts. +* [**Programming Prompts Collection**](./i18n/zh/prompts/02-编程提示词/): Dedicated prompts for the Vibe Coding process. +* [**System Prompt Construction Principles**](./i18n/zh/documents/00-基础指南/系统提示词构建原则.md): Comprehensive guide to building efficient AI system prompts. +* [**Development Experience Summary**](./i18n/zh/documents/00-基础指南/开发经验.md): Variable naming, file structure, coding standards, architectural principles, etc. +* [**General Project Architecture Template**](./i18n/zh/documents/00-基础指南/通用项目架构模板.md): Standard directory structures for various project types. +* [**Augment MCP Configuration Document**](./i18n/zh/documents/02-方法论/auggie-mcp配置文档.md): Augment context engine configuration instructions. +* [**System Prompts Collection**](./i18n/zh/prompts/01-系统提示词/): System prompts for AI development, including multi-version development specifications. +* [**External Resources Aggregation**](./i18n/zh/documents/04-资源/外部资源聚合.md): Curated GitHub repositories, AI tool platforms, prompt resources, and top bloggers. + +--- + +
+ +
+Encoding Model Performance Grading Reference + +## Encoding Model Performance Grading Reference + +It is recommended to only choose top-tier models for complex tasks to ensure optimal results and efficiency. + +* **Tier 1**: `codex-5.1-max-xhigh`, `claude-opus-4.5-xhigh`, `gpt-5.2-xhigh` +* **Tier 2**: `claude-sonnet-4.5`, `kimi-k2-thinking`, `minimax-m2`, `glm-4.6`, `gemini-3.0-pro`, `gemini-2.5-pro` +* **Tier 3**: `qwen3`, `SWE`, `grok4` + +--- + +
+ +
+Project Directory Structure Overview + +### Project Directory Structure Overview + +The core structure of this project `vibe-coding-cn` mainly revolves around knowledge management, AI prompt organization, and automation. Below is a simplified directory tree and descriptions of each part: + +``` +. +├── CODE_OF_CONDUCT.md # Community code of conduct, regulating contributor behavior. +├── CONTRIBUTING.md # Contribution guide, explaining how to contribute to this project. +├── GEMINI.md # AI assistant context document, including project overview, tech stack, and file structure. +├── LICENSE # Open source license file. +├── Makefile # Project automation scripts for code checking, building, etc. +├── README.md # Main project document, including project overview, usage guide, resource links, etc. +├── .gitignore # Git ignore file. +├── AGENTS.md # AI agent-related documents or configurations. +├── CLAUDE.md # Core behavior rules or configurations for the AI assistant. +│ +├── i18n/zh/documents/ # Stores various explanatory documents, experience summaries, and detailed configuration instructions. +│ ├── 00-基础指南/ # Methodologies and principles +│ ├── 04-资源/ # Templates and resources +│ └── 02-方法论/ # Tutorials and guides +│ +├── libs/ # Generic library code for project internal modularization. +│ ├── common/ # Common functional modules. +│ │ ├── models/ # Model definitions. +│ │ │ └── __init__.py +│ │ └── utils/ # Utility functions. +│ │ └── backups/ # Internal backup tools. +│ ├── database/ # Database related modules. +│ │ └── .gitkeep # Placeholder file to ensure the directory is tracked by Git. +│ └── external/ # External integration modules. +│ ├── my-nvim/ # User's Neovim configuration. +│ ├── prompts-library/ # Prompt library management tool (Excel-Markdown conversion). +│ │ ├── main.py # Main entry point for the prompt library management tool. +│ │ ├── scripts/ # Contains Excel and Markdown conversion scripts and configurations. +│ │ ├── prompt_excel/ # Stores raw prompt data in Excel format. +│ │ ├── prompt_docs/ # Stores Markdown prompt documents converted from Excel. +│ │ └── ... (other prompts-library internal files) +│ └── XHS-image-to-PDF-conversion/ # Xiaohongshu image to PDF conversion tool. +│ +├── i18n/zh/prompts/ # Centralized storage for all types of AI prompts. +│ ├── 00-元提示词/ # Advanced prompts for generating prompts. +│ ├── 01-系统提示词/ # AI system-level prompts, used to set AI behavior and framework. +│ │ └── ... (other system prompts) +│ │ +│ ├── 02-编程提示词/ # Prompt collection specifically for programming and code generation. +│ │ └── ... (specific programming prompt files) +│ │ +│ └── 03-用户提示词/ # User-defined or commonly used prompts. +│ ├── ASCII图生成.md # ASCII art generation prompt. +│ ├── 数据管道.md # Data pipeline processing prompt. +│ └── ... (other user prompts) +│ +├── i18n/zh/skills/ # Centralized storage for all types of skills. + ├── 00-元技能/ # Meta-skills directory + │ └── claude-skills/ # Meta-SKILL for generating SKILLS + ├── 01-AI工具/ # AI CLI and tools + │ └── headless-cli/ # Headless mode AI CLI calls + ├── 02-数据库/ # Database skills + ├── 03-加密货币/ # Cryptocurrency/quantitative trading + └── 04-开发工具/ # General development tools +``` + +--- + +
+ +## 📺 Demos & Outputs + +In a nutshell: Vibe Coding = **Plan-driven + Context fixation + AI pair execution**, turning "from idea to maintainable code" into an auditable pipeline, rather than an unmanageable monolith file. + +**What you get** +- A systematic prompt toolchain: `i18n/zh/prompts/01-系统提示词/` constrains AI behavior boundaries, `i18n/zh/prompts/02-编程提示词/` provides full-link scripts for requirement clarification, planning, and execution. +- Closed-loop delivery path: requirements → context documentation → implementation plan → step-by-step implementation → self-testing → progress recording, fully reviewable and transferable. + +
+⚙️ Architecture & Workflow + +## ⚙️ Architecture & Workflow + +Core Asset Mapping: +``` +i18n/zh/prompts/ + 00-元提示词/ # Advanced prompts for generating prompts + 01-系统提示词/ # System-level prompts constraining AI behavior boundaries + 02-编程提示词/ # Core prompts for requirement clarification, planning, and execution chain + 03-用户提示词/ # Reusable user-side prompts +i18n/zh/documents/ + 04-资源/代码组织.md, 04-资源/通用项目架构模板.md, 00-基础指南/开发经验.md, 00-基础指南/系统提示词构建原则.md etc. knowledge base +backups/ + 一键备份.sh, 快速备份.py # Local/remote snapshot scripts +``` + +```mermaid +graph TB + %% GitHub Compatible Simplified Version (using only basic syntax) + + subgraph ext_layer[External Systems and Data Sources Layer] + ext_contrib[Community Contributors] + ext_sheet[Google Sheets / External Tables] + ext_md[External Markdown Prompts] + ext_api[Reserved: Other Data Sources / APIs] + ext_contrib --> ext_sheet + ext_contrib --> ext_md + ext_api --> ext_sheet + end + + subgraph ingest_layer[Data Ingestion and Collection Layer] + excel_raw[prompt_excel/*.xlsx] + md_raw[prompt_docs/External MD Input] + excel_to_docs[prompts-library/scripts/excel_to_docs.py] + docs_to_excel[prompts-library/scripts/docs_to_excel.py] + ingest_bus[Standardized Data Frame] + ext_sheet --> excel_raw + ext_md --> md_raw + excel_raw --> excel_to_docs + md_raw --> docs_to_excel + excel_to_docs --> ingest_bus + docs_to_excel --> ingest_bus + end + + subgraph core_layer[Data Processing and Intelligent Decision Layer / Core] + ingest_bus --> validate[Field Validation and Normalization] + validate --> transform[Format Mapping Transformation] + transform --> artifacts_md[prompt_docs/Standardized MD] + transform --> artifacts_xlsx[prompt_excel/Exported XLSX] + orchestrator[main.py · scripts/start_convert.py] --> validate + orchestrator --> transform + end + + subgraph consume_layer[Execution and Consumption Layer] + artifacts_md --> catalog_coding[i18n/zh/prompts/02-编程提示词] + artifacts_md --> catalog_system[i18n/zh/prompts/01-系统提示词] + artifacts_md --> catalog_meta[i18n/zh/prompts/00-元提示词] + artifacts_md --> catalog_user[i18n/zh/prompts/03-用户提示词] + artifacts_md --> docs_repo[i18n/zh/documents/*] + artifacts_md --> new_consumer[Reserved: Other Downstream Channels] + catalog_coding --> ai_flow[AI Pair Programming Workflow] + ai_flow --> deliverables[Project Context / Plan / Code Output] + end + + subgraph ux_layer[User Interaction and Interface Layer] + cli[CLI: python main.py] --> orchestrator + makefile[Makefile Task Encapsulation] --> cli + readme[README.md Usage Guide] --> cli + end + + subgraph infra_layer[Infrastructure and Cross-Cutting Capabilities Layer] + git[Git Version Control] --> orchestrator + backups[backups/一键备份.sh · backups/快速备份.py] --> artifacts_md + deps[requirements.txt · scripts/requirements.txt] --> orchestrator + config[prompts-library/scripts/config.yaml] --> orchestrator + monitor[Reserved: Logging and Monitoring] --> orchestrator + end +``` + +--- + +
+ +
+📈 Performance Benchmarking (Optional) + +This repository is positioned as a "workflow and prompt" repository rather than a performance-oriented codebase. It is recommended to track the following observable metrics (currently mainly relying on manual recording, scores/traces can be marked in `progress.md`): + +| Metric | Meaning | Current Status / Suggestion | +|:---|:---|:---| +| Prompt Hit Rate | Proportion of one-time generation meeting acceptance criteria | To be recorded; mark 0/1 in progress.md after each task | +| Turnaround Time | Time from requirement to first runnable version | Mark timestamps during screen recording, or use CLI timer | +| Change Traceability | Whether context/progress/backup is updated synchronously | Through manual updates; can add git tags/snapshots in backup scripts | +| Example Coverage | Whether there are minimal runnable examples/tests | It is recommended that each example project retains README + test cases | + +
+ +--- + +## 🗺️ Roadmap + +```mermaid +gantt + title Project Development Roadmap + dateFormat YYYY-MM + section In Progress (2025 Q4) + Complete Demo GIFs and Example Projects: active, 2025-12, 30d + Refine External Resource Aggregation: active, 2025-12, 20d + section Upcoming (2026 Q1) + Auto-generate Prompts Index Script: 2026-01, 15d + One-click Demo/Verification CLI Workflow: 2026-01, 15d + Add Snapshot and Validation to Backup Script: 2026-02, 10d + section Mid-term (2026 Q2) + Templated Example Project Set: 2026-03, 30d + Multi-model Comparison and Evaluation Baseline: 2026-04, 30d +``` + +--- + +## 🎯 Original Repo Translation + +> The following content is translated from the original repository [EnzeD/vibe-coding](https://github.com/EnzeD/vibe-coding) + +To start Vibe Coding, you only need one of the following two tools: +- **Claude Opus 4.5**, used in Claude Code +- **gpt-5.1-codex.1-codex (xhigh)**, used in Codex CLI + +This guide applies to both the CLI terminal version and the VSCode extension version (both Codex and Claude Code have extensions, and the interface is updated). + +*(Note: Earlier versions of this guide used **Grok 3**, then switched to **Gemini 2.5 Pro**, and now we are using **Claude 4.5** (or **gpt-5.1-codex.1-codex (xhigh)**))* + +*(Note 2: If you want to use Cursor, please refer to [version 1.1](https://github.com/EnzeD/vibe-coding/tree/1.1.1) of this guide, but we believe it is currently not as powerful as Codex CLI or Claude Code)* + ---
-📝 Prompt Resources - -### Prompt Libraries - -| Resource | Link | Description | -|:---|:---|:---| -| Online Prompt Table | [Google Sheets](https://docs.google.com/spreadsheets/d/1ngoQOhJqdguwNAilCl1joNwTje7FWWN9WiI2bo5VhpU/edit?gid=2093180351#gid=2093180351&range=A1) | Recommended | -| Meta Prompt Library | [Google Sheets](https://docs.google.com/spreadsheets/d/1ngoQOhJqdguwNAilCl1joNwTje7FWWN9WiI2bo5VhpU/edit?gid=1770874220#gid=1770874220) | | -| System Prompts Repository | [GitHub](https://github.com/x1xhlol/system-prompts-and-models-of-ai-tools) | | -| Awesome ChatGPT Prompts | [GitHub](https://github.com/f/awesome-chatgpt-prompts) | | - -### Prompt Tools - -| Tool | Link | Description | -|:---|:---|:---| -| Skills Maker | [GitHub](https://github.com/yusufkaraaslan/Skill_Seekers) | Generates customized Skills | -| LangGPT | [GitHub](https://github.com/langgptai/LangGPT) | Structured prompt framework | - -### Prompt Tutorials - -| Tutorial | Link | Description | -|:---|:---|:---| -| Prompt Engineering Guide | [promptingguide.ai](https://www.promptingguide.ai/zh) | Chinese version | -| Learn Prompting | [learnprompting.org](https://learnprompting.org/zh-Hans/) | Chinese version | -| OpenAI Prompt Engineering | [platform.openai.com](https://platform.openai.com/docs/guides/prompt-engineering) | Official | -| Anthropic Prompt Engineering | [docs.anthropic.com](https://docs.anthropic.com/claude/docs/prompt-engineering) | Official | -| State-Of-The-Art Prompting | [Google Docs](https://docs.google.com/document/d/11tBoylc5Pvy8wDp9_i2UaAfDi8x02iMNg9mhCNv65cU/) | YC top tips | -| Vibe Coding 101 | [Google Drive](https://drive.google.com/file/d/1OMiqUviji4aI56E14PLaGVJsbjhOP1L1/view) | Beginner's Guide | - -
- ---- +⚙️ Full Setup Process
-👥 Communities and Forums - -### Telegram - -| Community | Link | Description | -|:---|:---|:---| -| Vibe Coding Exchange Group | [t.me/glue_coding](https://t.me/glue_coding) | | -| Vibe Coding Channel | [t.me/tradecat_ai_channel](https://t.me/tradecat_ai_channel) | | - -### Discord - -| Community | Link | Description | -|:---|:---|:---| -| Cursor Discord | [discord.gg/cursor](https://discord.gg/cursor) | | -| Anthropic Discord | [discord.gg/anthropic](https://discord.gg/anthropic) | | -| Cline Discord | [discord.gg/cline](https://discord.gg/cline) | | -| Aider Discord | [discord.gg/aider](https://discord.gg/Tv2uQnR88V) | | -| Windsurf Discord | [discord.gg/codeium](https://discord.gg/codeium) | | - -### Reddit - -| Community | Link | Description | -|:---|:---|:---| -| r/ChatGPT | [reddit.com/r/ChatGPT](https://www.reddit.com/r/ChatGPT/) | ChatGPT Community | -| r/ClaudeAI | [reddit.com/r/ClaudeAI](https://www.reddit.com/r/ClaudeAI/) | Claude Community | -| r/Bard | [reddit.com/r/Bard](https://www.reddit.com/r/Bard/) | Gemini Community | -| r/PromptEngineering | [reddit.com/r/PromptEngineering](https://www.reddit.com/r/PromptEngineering/) | Prompt Engineering | -| r/ChatGPTPromptGenius | [reddit.com/r/ChatGPTPromptGenius](https://www.reddit.com/r/ChatGPTPromptGenius/) | Prompt Sharing | -| r/LocalLLaMA | [reddit.com/r/LocalLLaMA](https://www.reddit.com/r/LocalLLaMA/) | Local LLM | - -### X (Twitter) - -| Community | Link | Description | -|:---|:---|:---| -| Vibe Coding Community | [x.com/communities](https://x.com/i/communities/1993849457210011871) | | -| Community Dry Goods Aggregation Page | [x.com/vibeverything](https://x.com/vibeverything/status/1999796188053438687) | | +1. Game Design Document +- Hand your game idea to **gpt-5.1-codex** or **Claude Opus 4.5**, and let it generate a concise **Game Design Document** in Markdown format, named `game-design-document.md`. +- Review and refine it yourself to ensure it aligns with your vision. It can be rough at first; the goal is to provide AI with the context of the game's structure and intent. Do not over-design; it will be iterated later.
---- -
-🐙 GitHub Featured Repositories - -### GitHub Discovery - -| Resource | Link | Description | -|:---|:---|:---| -| GitHub Topics | [github.com/topics](https://github.com/topics) | Browse repositories by topic | -| GitHub Trending | [github.com/trending](https://github.com/trending) | Trending repositories | - -### CLI Tools - -| Repository | Link | Description | -|:---|:---|:---| -| claude-code | [GitHub](https://github.com/anthropics/claude-code) | Anthropic official CLI | -| aider | [GitHub](https://github.com/paul-gauthier/aider) | AI pair programming tool | -| gpt-engineer | [GitHub](https://github.com/gpt-engineer-org/gpt-engineer) | Natural language code generation | -| open-interpreter | [GitHub](https://github.com/OpenInterpreter/open-interpreter) | Local code interpreter | -| continue | [GitHub](https://github.com/continuedev/continue) | Open-source AI code assistant | -| spec-kit | [GitHub](https://github.com/github/spec-kit) | GitHub official Spec-Driven development toolkit | -| opencode | [GitHub](https://github.com/opencode-ai/opencode) | Open-source terminal AI assistant, written in Go | -| oh-my-opencode | [GitHub](https://github.com/code-yeongyu/oh-my-opencode) | OpenCode configuration and plugins | -| cline | [GitHub](https://github.com/cline/cline) | VS Code autonomous programming Agent | -| gemini-cli | [GitHub](https://github.com/google-gemini/gemini-cli) | Google official CLI | - -### IDE Plugins - -| Repository | Link | Description | -|:---|:---|:---| -| copilot.vim | [GitHub](https://github.com/github/copilot.vim) | GitHub Copilot Vim plugin | -| codeium | [GitHub](https://github.com/Exafunction/codeium.vim) | Free AI code completion | -| avante.nvim | [GitHub](https://github.com/yetone/avante.nvim) | Neovim AI assistant plugin | -| codecompanion.nvim | [GitHub](https://github.com/olimorris/codecompanion.nvim) | Neovim AI programming companion | - -### Prompt Engineering - -| Repository | Link | Description | -|:---|:---|:---| -| awesome-chatgpt-prompts | [GitHub](https://github.com/f/awesome-chatgpt-prompts) | ChatGPT prompt collection | -| awesome-chatgpt-prompts-zh | [GitHub](https://github.com/PlexPt/awesome-chatgpt-prompts-zh) | Chinese prompts | -| system-prompts-and-models-of-ai-tools | [GitHub](https://github.com/x1xhlol/system-prompts-and-models-of-ai-tools) | AI tool system prompts | -| claude-code-system-prompts | [GitHub](https://github.com/Piebald-AI/claude-code-system-prompts) | Claude Code system prompts | -| LangGPT | [GitHub](https://github.com/langgptai/LangGPT) | Structured prompt framework | - -### Agent Frameworks - -| Repository | Link | Description | -|:---|:---|:---| -| langchain | [GitHub](https://github.com/langchain-ai/langchain) | LLM application development framework | -| autogen | [GitHub](https://github.com/microsoft/autogen) | Multi-Agent conversation framework | -| crewai | [GitHub](https://github.com/joaomdmoura/crewAI) | AI Agent collaboration framework | -| dspy | [GitHub](https://github.com/stanfordnlp/dspy) | Programmatic LLM framework | -| MCAF | [mcaf.managed-code.com](https://mcaf.managed-code.com/) | AI programming framework, defines AGENTS.md specification | -| smolagents | [GitHub](https://github.com/huggingface/smolagents) | HuggingFace lightweight Agent framework | -| pydantic-ai | [GitHub](https://github.com/pydantic/pydantic-ai) | Type-safe AI Agent framework | -| browser-use | [GitHub](https://github.com/browser-use/browser-use) | AI browser automation | - -### Learning Resources - -| Repository | Link | Description | -|:---|:---|:---| -| 2025 AI Engineer Reading List | [Latent.Space](https://www.latent.space/p/2025-papers) | 50 must-read papers covering LLM/RAG/Agent/CodeGen and 10 fields | -| prompt-engineering-guide | [GitHub](https://github.com/dair-ai/Prompt-Engineering-Guide) | Prompt Engineering Guide | -| generative-ai-for-beginners | [GitHub](https://github.com/microsoft/generative-ai-for-beginners) | Microsoft Generative AI tutorial | -| llm-course | [GitHub](https://github.com/mlabonne/llm-course) | LLM learning roadmap | -| ai-engineering | [GitHub](https://github.com/chiphuyen/aie-book) | AI Engineering practice | -| awesome-llm | [GitHub](https://github.com/Hannibal046/Awesome-LLM) | LLM resource compilation | -| vibe-vibe | [GitHub](https://github.com/datawhalechina/vibe-vibe) | Datawhale Vibe Coding tutorial | -| AI 编程最佳实践 | [GitHub](https://github.com/ninehills/blog/issues/97) | ninehills AI programming experience | - -### Utility Tools - -| Repository | Link | Description | -|:---|:---|:---| -| ollama | [GitHub](https://github.com/ollama/ollama) | Runs local LLMs | -| localai | [GitHub](https://github.com/mudler/LocalAI) | Local AI API | -| text-generation-webui | [GitHub](https://github.com/oobabooga/text-generation-webui) | Text Generation WebUI | -| lmstudio | [lmstudio.ai](https://lmstudio.ai/) | Local model GUI tool | -| jan | [GitHub](https://github.com/janhq/jan) | Open-source local AI assistant | -| repomix | [GitHub](https://github.com/yamadashy/repomix) | Packages codebases for AI context | -| gitingest | [GitHub](https://github.com/cyclotruc/gitingest) | Converts Git repositories to AI-friendly format | +2. Tech Stack and CLAUDE.md / Agents.md +- Let **gpt-5.1-codex** or **Claude Opus 4.5** recommend the most suitable tech stack for your game (e.g., ThreeJS + WebSocket for a multiplayer 3D game), save it as `tech-stack.md`. + - Ask it to propose the **simplest yet most robust** tech stack. +- Open **Claude Code** or **Codex CLI** in the terminal, use the `/init` command, which will read the two .md files you created and generate a set of rules to properly guide the large model. +- **Key: Always review the generated rules.** Ensure the rules emphasize **modularization** (multiple files) and prohibit **monoliths**. You may need to manually modify or supplement the rules. + - **Extremely Important:** Certain rules must be set to **"Always"**, ensuring that AI is forced to read them before generating any code. For example, add the following rules and mark them as "Always": + > ``` + > # Important Note: + > # Before writing any code, you must fully read memory-bank/@architecture.md (including full database structure) + > # Before writing any code, you must fully read memory-bank/@game-design-document.md + > # After completing any major feature or milestone, you must update memory-bank/@architecture.md + > ``` + - Other (non-Always) rules should guide AI to follow best practices for your tech stack (e.g., networking, state management). + - *If you want the cleanest code and most optimized project, this entire set of rule settings is mandatory.*
---- -
-🔧 Development Tools - -### IDEs & Editors - -| Tool | Link | Description | -|:---|:---|:---| -| VS Code | [code.visualstudio.com](https://code.visualstudio.com/) | Mainstream editor | -| Cursor | [cursor.com](https://cursor.com/) | AI-native editor, based on VS Code | -| Windsurf | [windsurf.com](https://windsurf.com/) | Codeium AI IDE | -| Neovim | [neovim.io](https://neovim.io/) | Keyboard-centric preference | -| LazyVim | [lazyvim.org](https://www.lazyvim.org/) | Neovim configuration framework | -| Zed | [zed.dev](https://zed.dev/) | High-performance editor, supports AI | -| Void | [voideditor.com](https://voideditor.com/) | Open-source AI code editor | -| PearAI | [trypear.ai](https://trypear.ai/) | Open-source AI IDE | - -### Terminal Tools - -| Tool | Link | Description | -|:---|:---|:---| -| Warp | [warp.dev](https://www.warp.dev/) | AI terminal | -| tmux | [GitHub](https://github.com/tmux/tmux) | Terminal multiplexer | -| zsh | [ohmyz.sh](https://ohmyz.sh/) | Shell enhancement | - -### Web Frameworks - -| Tool | Link | Description | -|:---|:---|:---| -| Django | [djangoproject.com](https://www.djangoproject.com/) | Python full-stack Web framework | - -### Database Tools - -| Tool | Link | Description | -|:---|:---|:---| -| DBeaver | [dbeaver.io](https://dbeaver.io/) | Universal database client | -| TablePlus | [tableplus.com](https://tableplus.com/) | Modern database GUI | - -### Visualization Tools - -| Tool | Link | Description | -|:---|:---|:---| -| Mermaid | [mermaid.js.org](https://mermaid.js.org/) | Text to diagrams | -| Excalidraw | [excalidraw.com](https://excalidraw.com/) | Hand-drawn style diagrams | -| NotebookLM | [notebooklm.google.com](https://notebooklm.google.com/) | AI note-taking tool | +3. Implementation Plan +- Provide the following to **gpt-5.1-codex** or **Claude Opus 4.5**: + - Game Design Document (`game-design-document.md`) + - Tech Stack Recommendation (`tech-stack.md`) +- Let it generate a detailed **Implementation Plan** (Markdown format), containing a series of step-by-step instructions for the AI developer. + - Each step should be small and specific. + - Each step must include tests to verify correctness. + - Strictly no code – only clear, specific instructions. + - Focus on the **basic game** first; full features will be added later.
---- -
-📖 Tutorials & Courses - -### Official Documentation - -| Document | Link | Description | -|:---|:---|:---| -| Claude Documentation | [docs.anthropic.com](https://docs.anthropic.com/) | Anthropic Official | -| OpenAI Documentation | [platform.openai.com](https://platform.openai.com/docs/) | OpenAI Official | -| Gemini Documentation | [ai.google.dev](https://ai.google.dev/docs) | Google Official | - -### Community Tutorials - -| Tutorial | Link | Description | -|:---|:---|:---| -| Conductor for Gemini CLI | [Google Blog](https://developers.googleblog.com/conductor-introducing-context-driven-development-for-gemini-cli/) | Context-driven development, Gemini CLI extension | -| Erge's Java Advanced Path | [javabetter.cn](https://javabetter.cn/) | Development tool configuration tutorial | -| Super Individual Resource List | [x.com/BiteyeCN](https://x.com/BiteyeCN/status/2000856243645157387) | | +4. Memory Bank +- Create a new project folder and open it in VSCode. +- Create a subfolder `memory-bank` in the project root directory. +- Place the following files into `memory-bank`: + - `game-design-document.md` + - `tech-stack.md` + - `implementation-plan.md` + - `progress.md` (create an empty file to record completed steps) + - `architecture.md` (create an empty file to record the purpose of each file)
---- +
-🌐 Network Configuration +🎮 Vibe Coding to Develop the Basic Game -### Proxy Clients - -| Tool | Link | Description | -|:---|:---|:---| -| FlClash | [GitHub](https://github.com/chen08209/FlClash/releases) | Cross-platform proxy client | - -### Network Services - -| Service | Link | Description | -|:---|:---|:---| -| Airport Service | [链接](https://xn--9kqz23b19z.com/#/register?code=35BcnKzl) | Approximately 6 CNY/month and up | - -
- ---- +Now for the most exciting part!
-💳 Payment Tools - -### Virtual Cards - -| Service | Link | Description | -|:---|:---|:---| -| Bybit Virtual Card | [bybit.com/cards](https://www.bybit.com/cards/?ref=YDGAVPN&source=applet_invite) | Used for international payments like cloud services registration | +Ensure Everything is Clear +- Open **Codex** or **Claude Code** in the VSCode extension, or launch Claude Code / Codex CLI in the project terminal. +- Prompt: Read all documents in `/memory-bank`. Is `implementation-plan.md` completely clear? What questions do you have for me to clarify, to make it 100% clear to you? +- It will typically ask 9-10 questions. After answering all of them, ask it to modify `implementation-plan.md` based on your answers to further refine the plan.
---- -
-📏 Rules/Rule Files - -### AI Programming Rules - -| Repository | Link | Description | -|:---|:---|:---| -| awesome-cursorrules | [GitHub](https://github.com/PatrickJS/awesome-cursorrules) | Cursor Rules collection | -| cursor.directory | [cursor.directory](https://cursor.directory/) | Cursor Rules online directory | -| dotcursorrules | [GitHub](https://github.com/pontusab/dotcursorrules) | .cursorrules template | -| claude-code-system-prompts | [GitHub](https://github.com/Piebald-AI/claude-code-system-prompts) | Claude Code system prompts | +Your First Implementation Prompt +- Open **Codex** or **Claude Code** (extension or terminal). +- Prompt: Read all documents in `/memory-bank`, then execute step 1 of the implementation plan. I will be responsible for running tests. Do not start step 2 until I verify the tests pass. After verification, open `progress.md` to record what you did for future developers, and then add new architectural insights to `architecture.md` to explain the purpose of each file. +- **Always** use "Ask" mode or "Plan Mode" (press `shift+tab` in Claude Code) first, and only let AI execute the step after you are satisfied. +- **Ultimate Vibe:** Install [Superwhisper](https://superwhisper.com), chat freely with Claude or gpt-5.1-codex using voice, no typing needed.
---- -
-📦 Templates/Scaffolding - -### Project Templates - -| Repository | Link | Description | -|:---|:---|:---| -| create-t3-app | [GitHub](https://github.com/t3-oss/create-t3-app) | Full-stack TypeScript scaffolding | -| create-next-app | [nextjs.org](https://nextjs.org/docs/app/api-reference/cli/create-next-app) | Next.js official scaffolding | -| vite | [GitHub](https://github.com/vitejs/vite) | Modern frontend build tool | -| fastapi-template | [GitHub](https://github.com/tiangolo/full-stack-fastapi-template) | FastAPI full-stack template | -| shadcn/ui | [ui.shadcn.com](https://ui.shadcn.com/) | React UI component library | +Workflow +- After completing step 1: + - Commit changes to Git (ask AI if you don't know how). + - Start a new chat (`/new` or `/clear`). + - Prompt: Read all files in memory-bank, read progress.md to understand previous work progress, then proceed to step 2 of the implementation plan. Do not start step 3 until I verify the tests. +- Repeat this process until the entire `implementation-plan.md` is completed.
---- +
-📚 Documentation/Knowledge Base Tools +✨ Add Detailed Features -### RAG Related - -| Tool | Link | Description | -|:---|:---|:---| -| RAGFlow | [GitHub](https://github.com/infiniflow/ragflow) | Open-source RAG engine | -| Dify | [GitHub](https://github.com/langgenius/dify) | LLM application development platform | -| AnythingLLM | [GitHub](https://github.com/Mintplex-Labs/anything-llm) | Private document AI assistant | -| Quivr | [GitHub](https://github.com/QuivrHQ/quivr) | Personal knowledge base AI | -| PrivateGPT | [GitHub](https://github.com/zylon-ai/private-gpt) | Private document Q&A | - -### Documentation Tools - -| Tool | Link | Description | -|:---|:---|:---| -| Docusaurus | [docusaurus.io](https://docusaurus.io/) | Meta open-source documentation framework | -| VitePress | [vitepress.dev](https://vitepress.dev/) | Vue-powered static site | -| Mintlify | [mintlify.com](https://mintlify.com/) | AI document generation | -| Zread | [zread.ai](https://zread.ai/) | AI repository reading tool | +Congratulations! You have built the basic game! It might still be rough and lack features, but now you can experiment and refine it as much as you want. +- Want fog effects, post-processing, special effects, sound effects? Better planes/cars/castles? Beautiful skies? +- For each major feature you add, create a new `feature-implementation.md`, writing short steps + tests. +- Continue to implement and test incrementally.
---- -
-✅ Code Quality/Testing - -### AI Code Review - -| Tool | Link | Description | -|:---|:---|:---| -| | | To be supplemented | - -
- ---- +🐞 Bug Fixes & Stuck Situations
-🚀 Deployment/DevOps - -### One-Click Deployment - -| Platform | Link | Description | -|:---|:---|:---| -| | | To be supplemented | +General Fixes +- If a prompt fails or breaks the project: + - Use `/rewind` in Claude Code to revert; for gpt-5.1-codex, commit to git more often and reset when needed. +- Error handling: + - **JavaScript errors:** Open browser console (F12), copy the error, paste it to AI; for visual issues, send screenshots. + - **Lazy solution:** Install [BrowserTools](https://browsertools.agentdesk.ai/installation), automatically copies errors and screenshots.
---- -
-🎯 Specific Domains - -### Web3/Blockchain - -| Tool | Link | Description | -|:---|:---|:---| -| | | To be supplemented | - -### Data Science/ML - -| Tool | Link | Description | -|:---|:---|:---| -| | | To be supplemented | +Tough Problems +- If truly stuck: + - Revert to the previous git commit (`git reset`), try again with new prompts. +- Extremely stuck: + - Use [RepoPrompt](https://repoprompt.com/) or [uithub](https://uithub.com/) to consolidate the entire codebase into one file, then throw it to **gpt-5.1-codex or Claude** for help.
---- +
-🇨🇳 Chinese Resource Zone +💡 Tips & Tricks -### Domestic Mirrors/Accelerators +
+Claude Code & Codex Usage Tips -| Resource | Link | Description | -|:---|:---|:---| -| | | To be supplemented | +- **Terminal Claude Code / Codex CLI:** Run in VSCode terminal, directly view diffs, feed context, without leaving the workspace. +- **Claude Code's `/rewind`:** One-click rollback to a previous state when iteration goes astray. +- **Custom Commands:** Create shortcut commands like `/explain $parameter` to trigger prompts: "Analyze the code in depth to fully understand how $parameter works. After understanding, tell me, and I will give you the next task." This makes the model load full context before modifying code. +- **Clean Context:** Frequently use `/clear` or `/compact` (to preserve historical conversations). +- **Time-saving trick (use at your own risk):** Use `claude --dangerously-skip-permissions` or `codex --yolo` to completely disable confirmation pop-ups. +
+ +
+Other Useful Tips + +- **Small modifications:** Use gpt-5.1-codex (medium) +- **Write top-tier marketing copy:** Use Opus 4.1 +- **Generate excellent 2D sprites:** Use ChatGPT + Nano Banana +- **Generate music:** Use Suno +- **Generate sound effects:** Use ElevenLabs +- **Generate videos:** Use Sora 2 +- **Improve prompt effectiveness:** + - Add a sentence: "Think slowly, no rush. It's important to strictly follow my instructions and execute perfectly. If my expression is not precise enough, please ask." + - In Claude Code, the intensity of keywords that trigger deep thinking: `think` < `think hard` < `think harder` < `ultrathink`. +
+ +
+ +
+❓ Frequently Asked Questions (FAQ) + +- **Q: I'm building an application, not a game. Is the process the same?** + - **A:** Essentially identical! Just replace GDD with PRD (Product Requirements Document). You can also use v0, Lovable, Bolt.new for quick prototyping, then move the code to GitHub, and clone it locally to continue development with this guide. + +- **Q: Your aerial combat game's plane model is amazing, but I can't make it with one prompt!** + - **A:** That wasn't one prompt, it was ~30 prompts + a dedicated `plane-implementation.md` file guiding it. Use precise instructions like "cut out space for ailerons on the wings" instead of vague instructions like "make a plane". + +- **Q: Why are Claude Code or Codex CLI stronger than Cursor now?** + - **A:** It's entirely a matter of personal preference. We emphasize that Claude Code can better leverage the power of Claude Opus 4.5, and Codex CLI can better leverage the power of gpt-5.1-codex. Cursor's utilization of both is not as good as the native terminal versions. Terminal versions can also work in any IDE, use SSH remote servers, etc., and custom commands, sub-agents, hooks, and other features can significantly improve development quality and speed in the long run. Finally, even if you only have a low-tier Claude or ChatGPT subscription, it's completely sufficient. + +- **Q: What if I don't know how to set up a multiplayer game server?** + - **A:** Ask your AI.
--- -## 📝 Contribution +## 📞 Contact Info -Found good resources? Welcome PRs to supplement! +- **GitHub**: [tukuaiai](https://github.com/tukuaiai) +- **Twitter / X**: [123olp](https://x.com/123olp) +- **Telegram**: [@desci0](https://t.me/desci0) +- **Telegram Chat Group**: [glue_coding](https://t.me/glue_coding) +- **Telegram Channel**: [tradecat_ai_channel](https://t.me/tradecat_ai_channel) +- **Email**: tukuai.ai@gmail.com (Replies may not be timely) + +--- + +## ✨ Support Project + +Please help, thank you, good people will be safe and sound forever🙏🙏🙏 + +- **Binance UID**: `572155580` +- **Tron (TRC20)**: `TQtBXCSTwLFHjBqTS4rNUp7ufiGx51BRey` +- **Solana**: `HjYhozVf9AQmfv7yv79xSNs6uaEU5oUk2USasYQfUYau` +- **Ethereum (ERC20)**: `0xa396923a71ee7D9480b346a17dDeEb2c0C287BBC` +- **BNB Smart Chain (BEP20)**: `0xa396923a71ee7D9480b346a17dDeEb2c0C287BBC` +- **Bitcoin**: `bc1plslluj3zq3snpnnczplu7ywf37h89dyudqua04pz4txwh8z5z5vsre7nlm` +- **Sui**: `0xb720c98a48c77f2d49d375932b2867e793029e6337f1562522640e4f84203d2e` + +--- + +### ✨ Contributors + +Thanks to all the developers who contributed to this project! + + + + + + +

Special thanks to the following members for their valuable contributions (in no particular order):
+@shao__meng | +@0XBard_thomas | +@Pluvio9yte | +@xDinoDeer | +@geekbb | +@GitHub_Daily | +@BiteyeCN | +@CryptoJHK +

+ +--- + +## 🤝 Contribute + +We warmly welcome contributions in all forms. If you have any ideas or suggestions for this project, please feel free to open an [Issue](https://github.com/tukuaiai/vibe-coding-cn/issues) or submit a [Pull Request](https://github.com/tukuaiai/vibe-coding-cn/pulls). + +Before you begin, please take the time to read our [**Contribution Guidelines (CONTRIBUTING.md)**](CONTRIBUTING.md) and [**Code of Conduct (CODE_OF_CONDUCT.md)**](CODE_OF_CONDUCT.md). + +--- + +## 📜 License + +This project is licensed under the [MIT](LICENSE) license. + +--- + +
+ +**If this project is helpful to you, please consider giving it a Star ⭐!** + +## Star History + + + + + + Star History Chart + + + +--- + +**Crafted with passion by [tukuaiai](https://github.com/tukuaiai), [Nicolas Zullo](https://x.com/NicolasZu), and [123olp](https://x.com/123olp)** + +[⬆ Back to Top](#vibe-coding-指南) +
+``` diff --git a/i18n/en/documents/04-resources/README.md b/i18n/en/documents/04-resources/README.md index 06c4aec..2a48cf1 100644 --- a/i18n/en/documents/04-resources/README.md +++ b/i18n/en/documents/04-resources/README.md @@ -1,9 +1,26 @@ -# 04-Resources +```markdown +# 📦 Resources -Templates, tools, and external resources. +> Templates, Tools, External Resources -## Contents +## 🗂️ Templates and Tools -- [Tool Collection](./Tool%20Collection.md) - AI tools and development utilities -- [Recommended Programming Books](./Recommended%20Programming%20Books.md) -- [External Resource Aggregation](./External%20Resource%20Aggregation.md) - Curated external resources +| Resource | Description | +|:---|:---| +| [General Project Architecture Template](./通用项目架构模板.md) | Standard directory structures for various project types | +| [Code Organization](./代码组织.md) | Best practices for code organization | +| [Tool Set](./工具集.md) | Commonly used development tools | + +## 📚 Learning Resources + +| Resource | Description | +|:---|:---| +| [Recommended Programming Books](./编程书籍推荐.md) | Curated selection of programming books | +| [Aggregated External Resources](./外部资源聚合.md) | Summary of AI tools, communities, and GitHub repositories | + +## 🔗 Related Resources +- [Fundamentals Guide](../00-基础指南/) - Core concepts and methodologies +- [Getting Started Guide](../01-入门指南/) - Environment setup +- [Methodology](../02-方法论/) - Tools and experience +- [Practice](../03-实战/) - Hands-on practice +``` diff --git a/i18n/en/documents/04-resources/Tool Collection.md b/i18n/en/documents/04-resources/Tool Collection.md index 688fb17..1798fc5 100644 --- a/i18n/en/documents/04-resources/Tool Collection.md +++ b/i18n/en/documents/04-resources/Tool Collection.md @@ -1,6 +1,7 @@ +``` # 🛠️ Toolset -> Vibe Coding Common Tools Quick Reference +> Quick reference for Vibe Coding tools ## 💻 IDEs and Plugins @@ -11,13 +12,13 @@ | [Cursor](https://cursor.com/) | AI-native editor | | [Continue](https://continue.dev/) | Open-source AI code assistant plugin | | Local History | VS Code local history plugin | -| Partial Diff | VS Code diff viewer plugin | +| Partial Diff | VS Code diff comparison plugin | ## 🤖 AI Models | Model | Description | |:---|:---| -| Claude Opus 4.5 | Strong coding capabilities | +| Claude Opus 4.5 | Strong code capabilities | | GPT-5.1 Codex | Complex logic processing | | Gemini 2.5 Pro | Free long context | @@ -25,7 +26,7 @@ | Tool | Description | |:---|:---| -| [Kiro](https://kiro.dev/) | AWS official, free Claude Opus | +| [Kiro](https://kiro.dev/) | AWS product, free Claude Opus | | [Droid](https://factory.ai/) | Multi-model CLI access | | Claude Code | Anthropic official CLI | | Codex CLI | OpenAI official CLI | @@ -35,17 +36,18 @@ | Website | Purpose | |:---|:---| -| [AI Studio](https://aistudio.google.com/) | Google free Gemini | -| [ChatGPT](https://chatgpt.com/) | OpenAI conversation | -| [Zread](https://zread.ai/) | AI repository reading | -| [GitHub](https://github.com/) | Code hosting | -| [Mermaid Chart](https://www.mermaidchart.com/) | Text to diagram | -| [NotebookLM](https://notebooklm.google.com/) | AI note-taking tool | -| [Google Sheets](https://docs.google.com/spreadsheets/) | Online spreadsheets | -| [Apps Script](https://script.google.com/) | Google scripts | -| [Z-Library](https://z-lib.fm/) | E-book resources | -| [Bilibili](https://www.bilibili.com/) | Video tutorials | +| [AI Studio](https://aistudio.google.com/) | Google Free Gemini | +| [ChatGPT](https://chatgpt.com/) | OpenAI Conversation | +| [Zread](https://zread.ai/) | AI Repository Reading | +| [GitHub](https://github.com/) | Code Hosting | +| [Mermaid Chart](https://www.mermaidchart.com/) | Text to Diagram | +| [NotebookLM](https://notebooklm.google.com/) | AI Note Tool | +| [Google Sheets](https://docs.google.com/spreadsheets/) | Online Spreadsheets | +| [Apps Script](https://script.google.com/) | Google Script | +| [Z-Library](https://z-lib.fm/) | E-book Resources | +| [Bilibili](https://www.bilibili.com/) | Video Tutorials | ## 🔗 More Resources See [External Resources Aggregation](./外部资源聚合.md) +``` diff --git a/i18n/zh/documents/03-实战/fate-engine-dev/ascii可视化-prompt.md b/i18n/zh/documents/03-实战/fate-engine-dev/ascii可视化-prompt.md new file mode 100644 index 0000000..052edfe --- /dev/null +++ b/i18n/zh/documents/03-实战/fate-engine-dev/ascii可视化-prompt.md @@ -0,0 +1 @@ +# 任务说明：指定项目仓库的系统分析与可视化建模## 角色设定你是一名 **资深软件架构师 / 系统分析专家**，具备从实际代码仓库中进行架构逆向分析、系统抽象与技术文档生成的能力。## 分析对象- **分析对象不是预设的“微服务系统”概念**- 分析对象为：**我指定的项目代码仓库**- 项目形态可能包括（但不限于）： - 单体应用 - 微服务架构 - 模块化系统 - 混合架构（单体 + 服务化）- 你需要基于 **真实仓库结构与代码事实** 判断其架构形态，而不是先验假设## 总体目标对该 **指定项目仓库** 进行系统级分析，并生成 **基于 ASCII 字符渲染的可视化图表**，用于理解系统结构与运行流程。## 分析任务要求### 1. 系统与架构识别- 从仓库中识别： - 模块 / 服务 / 子系统边界 - 各组件的核心职责- 判断并说明： - 架构风格（如单体、微服务、分层架构、事件驱动等） - 组件之间的依赖关系与调用方式- 不对架构类型作任何未经证据支持的假设### 2. 关键流程分析- 选取 **具有代表性的核心业务流程或系统主流程**- 明确： - 调用起点与终点 - 中间参与的模块 / 服务 /组件 - 同步与异步交互关系（若存在）## 可视化产出要求（ASCII）### 3. 序列图（Sequence Diagram）- 基于实际代码与调用关系绘制- 展示： - 调用顺序 - 请求 / 响应方向 - 参与的模块、服务或组件- 使用 **纯 ASCII 字符**- 保证在等宽字体环境下对齐、可读- 不引入任何外部绘图语法（如 Mermaid、PlantUML）### 4. 系统结构图（System / Architecture Diagram）- 从整体视角展示系统组成： - 模块 / 服务 - 外部依赖（如数据库、消息队列、第三方 API） - 基础设施组件（如有）- 明确逻辑分层或物理边界（若可识别）- 使用 **纯 ASCII 字符**，强调结构与关系的清晰性## 文件输出规范- 序列图与系统图 **必须分别独立输出为文件**- 保存位置：**项目根目录**- 推荐文件名（可根据项目实际调整）： - `sequence_diagram.txt` - `system_architecture.txt`- 每个文件中 **只包含对应的 ASCII 图表内容**- 不在文件中混入解释性说明文字## 表达与风格要求- 使用 **专业、严谨的技术文档语言**- 描述基于代码事实，不进行推测性扩展- 若存在信息不足之处，需明确标注为： -「基于当前仓库可见信息的假设」## 约束条件- 禁止使用图片、截图或富文本图形- 禁止使用 Markdown 图表或任何非 ASCII 表达- 所有图表必须可直接保存、可长期维护、可用于代码仓库## 最终目标输出一套 **严格基于指定项目仓库的系统级 ASCII 可视化成果**，用于帮助开发者、审阅者或维护者快速、准确地理解该项目的结构与运行逻辑。 \ No newline at end of file diff --git a/i18n/zh/documents/03-实战/fate-engine-dev/完整性检查-prompt.md b/i18n/zh/documents/03-实战/fate-engine-dev/完整性检查-prompt.md new file mode 100644 index 0000000..4ede42b --- /dev/null +++ b/i18n/zh/documents/03-实战/fate-engine-dev/完整性检查-prompt.md @@ -0,0 +1 @@ +"# 系统性代码与功能完整性检查提示词（优化版）## 角色设定你是一名**资深系统架构师与代码审计专家**，具备对生产级 Python 项目进行深度静态与逻辑审查的能力。## 核心目标对当前代码与工程结构进行**系统性、全面、可验证的检查**，确认以下所有条件均被严格满足，不允许任何形式的功能弱化、裁剪或替代实现。---## 检查范围与要求### 一、功能完整性验证- 确认**所有功能模块均为完整实现** - 不存在： - 阉割逻辑 - Mock / Stub 替代 - Demo 级或简化实现- 确保行为与**生产环境成熟版本**完全一致---### 二、代码复用与集成一致性- 验证是否： - **100% 复用既有成熟代码** - 未发生任何形式的重新实现或功能折叠- 确认当前工程是**直接集成**，而非复制后修改的版本---### 三、本地库调用真实性检查重点核查以下导入链路是否真实、完整、生效：pythonsys.path.append('/home/lenovo/.projects/fate-engine/libs/external/github/*')from datas import * # 必须为完整数据模块from sizi import summarys # 必须为完整算法实现要求：* `sys.path` 引入路径真实存在且指向**生产级本地库*** `datas` 模块： * 包含全部数据结构、接口与实现 * 非裁剪版 / 非子集* `sizi.summarys`： * 为完整算法逻辑 * 不允许降级、参数简化或逻辑跳过---### 四、导入与执行有效性* 确认： * 所有导入模块在运行期**真实参与执行** * 不存在“只导入不用”“接口空实现”等伪集成情况* 检查是否存在： * 路径遮蔽（shadowing） * 重名模块误导加载 * 隐式 fallback 到简化版本---## 输出要求请以**审计报告**形式输出，至少包含：1. 检查结论（是否完全符合生产级完整性）2. 每一项检查的明确判断（通过 / 不通过）3. 若存在问题，指出： * 具体模块 * 风险等级 * 可能造成的后果**禁止模糊判断与主观推测，所有结论必须基于可验证的代码与路径分析。**" \ No newline at end of file diff --git a/i18n/zh/documents/03-实战/fate-engine-dev/胶水开发要求-prompt.md b/i18n/zh/documents/03-实战/fate-engine-dev/胶水开发要求-prompt.md new file mode 100644 index 0000000..3042baa --- /dev/null +++ b/i18n/zh/documents/03-实战/fate-engine-dev/胶水开发要求-prompt.md @@ -0,0 +1 @@ +# 胶水开发要求（强依赖复用 / 生产级库直连模式）## 角色设定你是一名**资深软件架构师与高级工程开发者**，擅长在复杂系统中通过强依赖复用成熟代码来构建稳定、可维护的工程。## 总体开发原则本项目采用**强依赖复用的开发模式**。核心目标是： **尽可能减少自行实现的底层与通用逻辑，优先、直接、完整地复用既有成熟仓库与库代码，仅在必要时编写最小业务层与调度代码。**---## 依赖与仓库使用要求### 一、依赖来源与形式- 允许并支持以下依赖集成方式： - 本地源码直连（`sys.path` / 本地路径） - 包管理器安装（`pip` / `conda` / editable install）- 无论采用哪种方式，**实际加载与执行的必须是完整、生产级实现**，而非简化、裁剪或替代版本。---### 二、强制依赖路径与导入规范在代码中，必须遵循以下依赖结构与导入形式（示例）：```pythonsys.path.append('/home/lenovo/.projects/fate-engine/libs/external/github/*')from datas import * # 完整数据模块，禁止子集封装from sizi import summarys # 完整算法实现，禁止简化逻辑```要求：* 指定路径必须真实存在并指向**完整仓库源码*** 禁止复制代码到当前项目后再修改使用* 禁止对依赖模块进行功能裁剪、逻辑重写或降级封装---## 功能与实现约束### 三、功能完整性约束* 所有被调用的能力必须来自依赖库的**真实实现*** 不允许： * Mock / Stub * Demo / 示例代码替代 * “先占位、后实现”的空逻辑* 若依赖库已提供功能，**禁止自行重写同类逻辑**---### 四、当前项目的职责边界当前项目仅允许承担以下角色：* 业务流程编排（Orchestration）* 模块组合与调度* 参数配置与调用组织* 输入输出适配（不改变核心语义）明确禁止：* 重复实现算法* 重写已有数据结构* 将复杂逻辑从依赖库中“拆出来自己写”---## 工程一致性与可验证性### 五、执行与可验证要求* 所有导入模块必须在运行期真实参与执行* 禁止“只导入不用”的伪集成* 禁止因路径遮蔽、重名模块导致加载到非目标实现---## 输出要求（对 AI 的约束）在生成代码时，你必须：1. 明确标注哪些功能来自外部依赖2. 不生成依赖库内部的实现代码3. 仅生成最小必要的胶水代码与业务逻辑4. 假设依赖库是权威且不可修改的黑箱实现**本项目评价标准不是“写了多少代码”，而是“是否正确、完整地站在成熟系统之上构建新系统”。**你需要处理的是： \ No newline at end of file diff --git a/i18n/zh/documents/03-实战/fate-engine-dev/问题描述-prompt.md b/i18n/zh/documents/03-实战/fate-engine-dev/问题描述-prompt.md new file mode 100644 index 0000000..2b5d5be --- /dev/null +++ b/i18n/zh/documents/03-实战/fate-engine-dev/问题描述-prompt.md @@ -0,0 +1 @@ +# 任务说明（System Prompt）你是一名**高级软件架构顾问与技术问题分析专家**。 你的任务是：**对当前代码项目中遇到的问题进行系统性、结构化、可诊断的完整描述**，以便后续进行高质量的技术分析、调试、重构或方案设计。---## 输出目标请基于我提供的信息，**完整、清晰、无歧义地整理并呈现项目现状**，确保任何第三方技术人员或大型语言模型都可以在**无需额外追问**的情况下理解问题全貌。---## 输出内容结构（必须严格遵循）请按照以下固定结构输出内容：### 1. 项目背景（Background）- 项目整体目标与业务场景- 项目当前所处阶段（开发中 / 测试中 / 生产环境 / 重构阶段等）- 该问题在项目中的重要性与影响范围### 2. 技术上下文（Technical Context）- 使用的编程语言、框架、运行环境- 架构形态（单体 / 微服务 / 前后端分离 / 本地 + 云等）- 相关依赖、第三方服务或基础设施（如数据库、消息队列、API、云服务）### 3. 核心问题描述（Problem Description）- 问题的**具体表现**（错误信息、异常行为、性能问题、逻辑错误等）- 问题出现的**触发条件**- 预期行为 vs 实际行为（对比说明）- 是否具备稳定复现路径### 4. 相关实体（Entities）- 涉及的核心模块 / 类 / 函数 / 文件- 关键数据结构或业务对象- 相关角色（如用户、服务、进程、线程等）### 5. 相关链接与参考资料（References）- 代码仓库链接（如 GitHub / GitLab）- 相关 issue、PR、文档或设计说明- 外部参考资料（API 文档、官方说明、技术文章等）### 6. 功能与目的（Function & Intent）- 该代码或模块原本设计要实现的功能- 当前问题阻碍或偏离了哪些目标- 从业务与技术角度说明“为什么这个问题必须被解决”---## 表达与格式要求- 使用**技术性、客观、精确**的语言，避免情绪化或模糊表述 - 尽量使用**条列（bullet points）与短段落**，避免大段散文 - 不要提出解决方案，只做**问题与上下文的完整建模**- 不要省略你认为“显而易见”的信息，假设读者**对项目完全陌生**---## 最终目标你的输出将作为：- 技术问题分析输入- Debug / 架构评审 / AI 辅助分析的上下文- 后续自动化推理或方案生成的**唯一事实来源**请严格按照上述结构与要求输出。 \ No newline at end of file diff --git a/i18n/zh/documents/03-实战/web-app/.gitkeep b/i18n/zh/documents/03-实战/web-app/.gitkeep deleted file mode 100644 index e69de29..0000000