本文档为ai根据你的意愿写代码可复制到任意软件项目中使用。目标建立一套可复现、可审查、可追溯的 AI 辅助开发环境将 VS Code、Cline 与 OpenSpec 工作流结合起来支持“先规划、再确认、再实现、再验证”的工程实践。1. 适用场景本配置适用于以下类型项目Python、Java、Node.js、前端、后端、算法或多语言混合项目。希望使用 Cline / GPT 类 AI Agent 辅助开发、重构、排查和文档编写的项目。需要在代码变更前明确需求范围、设计方案、验收标准的团队。对可维护性、可追溯性、交接质量和工程治理有要求的项目。不建议用于临时脚本或一次性实验项目。无需审查、无需沉淀需求文档的极小型任务。包含高敏感数据但尚未建立脱敏与访问控制机制的环境。2. 推荐基础环境2.1 操作系统与终端推荐环境类别建议操作系统Linux / macOS / Windows WSL2Shellbash / zsh / PowerShell编辑器Visual Studio Code版本控制GitAI AgentCline VS Code 扩展规格工作流OpenSpec2.2 常用语言工具按项目实际技术栈安装技术栈建议工具PythonPython 3.9、Conda/venv、pip、pytest、ruff、blackNode.js / 前端Node.js LTS、npm/pnpm/yarn、ESLint、PrettierJava / SpringJDK 17 或 21、Maven/Gradle容器化Docker / Docker ComposeAPI 调试curl、HTTPie、Postman 或 VS Code REST Client原则文档中记录“工具类型、推荐版本范围、安装方式”不要记录个人机器绝对路径、内网地址、账号、Token 或密钥。3. 推荐目录结构在项目根目录建议放置以下文件your-project/ ├── .vscode/ │ ├── settings.json # VS Code 工作区配置 │ ├── extensions.json # 推荐扩展可选 │ └── launch.json # 调试配置可选 ├── .clinerules # Cline 仓库级规则 ├── AGENTS.md # AI Agent / 协作者规则 ├── openspec/ │ ├── project.md # 项目背景、技术栈、约束 │ ├── specs/ # 已生效能力规格 │ └── changes/ │ └── change-id/ │ ├── proposal.md # 变更动机、范围、影响 │ ├── tasks.md # 实施清单 │ └── specs/ │ └── capability/ │ └── spec.md # 行为/能力规格增量 ├── README.md ├── doc/ └── src/4. VS Code 通用配置4.1.vscode/settings.json模板适用于 Linux/macOS/WSL 项目{terminal.integrated.defaultProfile.linux:bash-with-rcfile,terminal.integrated.profiles.linux:{bash-with-rcfile:{path:/bin/bash,args:[--rcfile,${env:HOME}/.bashrc,-i]}},files.eol:\n,editor.formatOnSave:false,markdown.preview.breaks:true,python-envs.defaultEnvManager:ms-python.python:venv,python-envs.defaultPackageManager:ms-python.python:pip,java.configuration.updateBuildConfiguration:disabled}如果项目统一使用 Conda可改为{python-envs.defaultEnvManager:ms-python.python:conda,python-envs.defaultPackageManager:ms-python.python:conda}4.2.vscode/extensions.json模板{recommendations:[saoudrizwan.claude-dev,ms-python.python,ms-python.vscode-pylance,ms-python.debugpy,redhat.vscode-yaml,shd101wyy.markdown-preview-enhanced,esbenp.prettier-vscode,dbaeumer.vscode-eslint,vue.volar,vscjava.vscode-java-pack,vmware.vscode-spring-boot,ms-azuretools.vscode-docker]}说明Cline 扩展 ID 可能随版本或市场发布信息变化如推荐列表无法安装请在 VS Code 扩展市场搜索Cline并以官方页面为准。4.3 配置原则工作区配置只放项目相关设置不写个人隐私路径。统一换行符、格式化策略、语言环境管理方式。自动格式化建议默认关闭待团队统一 formatter 后再开启。调试配置、任务配置中不要写真实密钥或私有服务地址。5. Cline 通用配置5.1 安装方式打开 VS Code。在 Extensions 中搜索并安装Cline。配置模型供应商例如 OpenAI、Anthropic、OpenRouter、Azure OpenAI 或本地模型网关。将 API Key 存放在 VS Code 用户级配置、系统密钥管理器或受控环境变量中。不要把 API Key 写入仓库文件。5.2.clinerules通用模板# Cline Workspace Rules This repository uses OpenSpec for non-trivial feature work, behavior changes, configuration changes, and documentation changes. Before modifying source/config/docs, Cline must: 1. Read openspec/project.md. 2. Understand the relevant files and existing conventions. 3. Create OpenSpec artifacts under openspec/changes/change-id/: - proposal.md - tasks.md - specs/capability/spec.md when behavior/API/user-visible output changes 4. Ask for explicit human confirmation before implementation. 5. Keep implementation aligned with the approved proposal. 6. Update tasks.md as work progresses. Security rules: - Do not print, copy, or commit API keys, tokens, passwords, private certificates, production credentials, or sensitive customer data. - Mask values from .env, secret managers, CI variables, and deployment configs. - Prefer minimal, focused changes. - Run or suggest relevant validation commands before completion.5.3 Cline 使用建议场景推荐做法新功能先让 Cline 创建 OpenSpec 草案人工确认后再实现Bug 修复提供复现步骤、日志、期望行为让 Cline 定位最小修改点重构明确“不改变外部行为”要求先列风险与验证方式文档要求基于实际文件调研避免凭空编写测试优先补充轻量、可自动运行的测试敏感配置只记录变量名和用途不输出真实值6. OpenSpec 通用配置6.1openspec/project.md模板# Project Overview ## Purpose Describe the project purpose, users, and core business value. ## Tech Stack - Runtime/language: - Backend: - Frontend: - Database/storage: - Infrastructure: - AI/model components: ## Conventions ### Code Style - Follow existing project style. - Keep changes focused and reviewable. - Prefer small incremental changes over large rewrites. ### Architecture - Document important module boundaries here. - Keep domain boundaries clear. - Avoid changing public APIs unless explicitly approved. ### Testing - Prefer existing build/test commands. - Add or update tests for non-trivial behavior changes. - Document manual verification steps when automated tests are unavailable. ### Git Workflow - Create an OpenSpec change before implementing non-trivial features or behavior changes. - Obtain explicit human confirmation before implementation. - Keep implementation aligned with the approved proposal. ## Important Constraints - Preserve backward compatibility unless an approved proposal requires a breaking change. - Do not modify vendored dependencies unless explicitly requested. - Do not expose secrets, credentials, or private data.6.2proposal.md模板## Why Explain the motivation and problem being solved. ## What Changes - Change item 1 - Change item 2 ## Out of Scope - Explicitly list what will not be changed. ## Impact - Affected modules: - Compatibility impact: - Risk level: - Validation plan:6.3tasks.md模板## Implementation Checklist - [ ] Review project rules and relevant files. - [ ] Confirm requirements and constraints. - [ ] Implement the approved change. - [ ] Add or update tests/documentation as needed. - [ ] Run validation commands. - [ ] Update this checklist and summarize results.6.4spec.md模板## ADDED Requirements ### Requirement: Capability name The system SHALL describe the required behavior. #### Scenario: Scenario name - **WHEN** condition/action - **THEN** expected result如是修改已有行为可使用## MODIFIED Requirements ### Requirement: Existing requirement name ...如是删除能力可使用## REMOVED Requirements ### Requirement: Removed requirement name ...7. 通用开发工作流提出需求 ↓ Cline 调研 README / openspec/project.md / 相关代码 ↓ 创建 openspec/changes/change-id/ 草案 ↓ 人工确认 proposal / tasks / spec ↓ Cline 实施代码、配置或文档变更 ↓ 执行测试、构建、静态检查或手工验证 ↓ 更新 tasks.md ↓ 输出变更摘要、验证结果、风险和后续建议7.1 推荐 change-id 命名使用动词短语保持小写短横线风格add-user-login fix-order-timeout refactor-payment-service update-dev-environment-doc improve-search-ranking7.2 推荐验证命令模板按项目类型选择# Pythonpython-mpytest python-mcompileall src tests ruff check.black--check.# Node.js / 前端npmrun lintnpmruntestnpmrun build# Java / Mavenmvntestmvn clean package# Dockerdockercompose configdockercompose up--build8. 脱敏与安全规范8.1 不应写入仓库的内容API Key、Access Token、Refresh Token。密码、私钥、证书、Cookie、Session。生产数据库地址、生产账号、生产日志原文。客户隐私数据、内部 IP、内网域名、专有模型下载地址。个人主目录绝对路径、个人用户名、个人 IDE 全局配置。8.2 文档中的推荐写法推荐API_BASE_URLconfigured-by-env OPENAI_API_KEYset-in-user-secret-store DATABASE_URLconfigured-in-deployment不推荐OPENAI_API_KEYsk-xxxxxxxx DATABASE_URLreal-database-url-with-password /absolute/path/to/private/project8.3.gitignore建议# secrets .env .env.* !.env.example *.pem *.key *.p12 *.crt # local IDE/user files .vscode/settings.local.json .idea/ # runtime outputs logs/ outputs/ tmp/ # dependencies/build node_modules/ dist/ build/ target/ .venv/ __pycache__/ .pytest_cache/8.4.env.example模板# API service address API_BASE_URLhttp://localhost:8000 # AI model provider key; set the real value in local secret storage or untracked .env OPENAI_API_KEYyour-api-key # Optional runtime mode APP_ENVdevelopment9. 项目开发优势引入 VS Code Cline OpenSpec 后项目开发通常会获得以下收益。9.1 需求边界清晰OpenSpec 要求先写 proposal、tasks 和必要的 spec让需求目标、影响范围、非目标和验收方式提前明确减少边写边改和范围蔓延。9.2 AI 修改更可控Cline 不直接进入实现而是先调研、规划、等待人工确认再执行修改。这样可以降低 AI 误改、过度重构、忽略项目约束的风险。9.3 多技术栈协作更顺畅对于包含前端、后端、脚本、数据库、模型或基础设施的项目Cline 可以跨文件理解上下文OpenSpec 固定变更边界VS Code 提供统一开发入口。9.4 变更历史可追溯每个非平凡变更都有独立目录记录为什么改。改什么。不改什么。如何验收。任务是否完成。后续交接、复盘和审查更容易。9.5 新人上手更快新人可以按顺序阅读README.md理解项目用途。openspec/project.md理解项目约束。.clinerules/AGENTS.md理解 AI 协作规则。openspec/changes/*理解近期变更背景。本文档复现通用开发环境。9.6 工程治理可以渐进推进无需一次性建立复杂流程可以先从以下最小集合开始.clinerules AGENTS.md openspec/project.md openspec/changes/change-id/proposal.md openspec/changes/change-id/tasks.md后续再逐步补充测试、CI、代码规范、架构文档和自动化检查。10. 最小落地清单如果只想快速落地建议按以下顺序执行安装 VS Code。安装 Cline 扩展并配置模型供应商。在项目根目录创建.clinerules。在项目根目录创建AGENTS.md。创建openspec/project.md。为第一个非平凡变更创建openspec/changes/change-id/proposal.md和tasks.md。让 Cline 在实现前等待人工确认。为项目补充至少一个可运行的验证命令。在交付时输出修改文件、验证结果和风险说明。11. 维护建议每个项目维护自己的.clinerules和AGENTS.md不要完全依赖个人全局提示词。每次非平凡变更都保留 OpenSpec 记录。定期清理过期 change 或归档已完成规格。文档只记录通用配置、变量名和用途不记录真实密钥或个人路径。团队应约定哪些变更必须走 OpenSpec哪些小修可以直接修改。推荐把验证命令写入 README、Makefile、package scripts 或 CI 配置方便 Cline 自动执行。