在开发过程中我们常常面临一个挑战如何高效地管理一个结构清晰、规范统一的项目目录尤其是在团队协作或接手新项目时混乱的目录结构、缺失的配置文件、不统一的依赖管理往往会让开发者花费大量时间在“找文件”和“配环境”上而不是专注于核心业务逻辑。CodeBuddy 作为一款智能的 AI 编程助手其“项目规则”功能正是为了解决这一痛点而生。它能够根据预设的规则自动创建和维护标准化的项目结构确保从项目诞生之初就走在正确的轨道上。本文将深入解析 CodeBuddy 的“创建项目规则”功能。无论你是初次接触 CodeBuddy 的新手还是希望提升团队项目规范性的资深开发者都能从本文中获得一套完整的实操方案。我们将从核心概念讲起逐步深入到规则的定义、配置、实战应用并最终探讨如何将其融入团队的最佳实践。学完后你将能够熟练运用 CodeBuddy 项目规则一键生成结构清晰、配置完备的标准化项目模板。1. 理解 CodeBuddy 项目规则从混乱到秩序在深入技术细节之前我们首先要理解“项目规则”究竟解决了什么问题以及它在 CodeBuddy 生态中扮演的角色。1.1 什么是项目规则简单来说项目规则是一套预定义的、可执行的指令集用于自动化地创建和初始化一个新项目的目录结构、基础文件、依赖配置以及环境设置。你可以把它想象成一个高度智能且可定制的“项目脚手架生成器”。传统上我们可能会手动创建src、tests、docs目录复制粘贴.gitignore、README.md、package.json或pom.xml等文件然后逐一安装依赖。这个过程重复、枯燥且容易出错。CodeBuddy 的项目规则将这一系列操作封装起来你只需要描述或选择规则它就能在瞬间为你搭建好一个“五脏俱全”的项目骨架。1.2 为什么需要它核心价值分析提升启动效率将数分钟甚至更长的初始化时间缩短到几秒钟让开发者能立刻开始编码。保证一致性在团队中强制执行统一的目录结构和开发规范新成员能快速上手减少沟通成本。减少人为错误避免遗漏关键配置文件如.env.example,.dockerignore或配置错误。集成最佳实践可以将安全扫描配置、代码格式化工具Prettier, Black、静态检查ESLint, SonarQube等直接内置到规则中让新项目一开始就具备高质量代码的基因。知识沉淀将团队积累的项目模板经验固化下来形成可复用的资产。1.3 CodeBuddy 项目规则与相关概念区分在搜索热词中我们看到了codebuddy skills、workbuddy等。这里做一个简要区分帮助你更精准地定位“项目规则”CodeBuddy Skills这是 CodeBuddy 的“技能”或“插件”系统。一个“项目规则”本质上可以看作是一个或多个Skills的组合。例如一个“创建 Spring Boot 项目”的规则可能调用了“创建 Maven 项目结构”、“添加 Spring Boot 依赖”、“配置 application.yml”等多个 Skills。CodeBuddy vs WorkBuddy根据网络信息WorkBuddy 可能是另一款侧重于工作流自动化的工具。而 CodeBuddy 更聚焦于代码编写、项目管理和开发辅助。本文讨论的“项目规则”是 CodeBuddy 的核心功能之一。Playwright MCP这可能指的是 CodeBuddy 通过 Model Context Protocol (MCP) 集成 Playwright 进行自动化测试的能力。一个高级的项目规则可以集成此类 Skill在创建项目时自动生成基础的 E2E 测试目录和示例。理解了这些我们就可以开始动手了。2. 环境准备与基础配置在开始定义和使用项目规则之前你需要确保 CodeBuddy 已正确安装并配置。2.1 安装与激活 CodeBuddyCodeBuddy 通常以 IDE 插件如 VS Code 扩展或独立应用程序的形式提供。本文以VS Code 扩展为例这是最常见的使用方式。打开 VS Code。进入扩展市场 (CtrlShiftX 或 CmdShiftX)。搜索CodeBuddy。找到官方扩展并点击“安装”。安装完成后你需要在 CodeBuddy 中配置 API Key 以激活其 AI 能力。这对应了热词中的“vscode中如何通过apikey使用codebuddy”。2.2 配置 API Key在 VS Code 中点击侧边栏的 CodeBuddy 图标通常是一个机器人或特定的 Logo。如果未登录界面会引导你进行注册或登录。登录后找到设置Settings或账户Account相关选项。在 API 配置部分输入你从 CodeBuddy 平台获取的 API Key。注意API Key 是私密信息切勿泄露。通常你可以在 CodeBuddy 的官方网站用户中心找到生成和管理 API Key 的地方。正确配置后CodeBuddy 的聊天界面和命令面板就应该可以正常使用了。你可以通过CtrlShiftP(或CmdShiftP) 打开命令面板输入CodeBuddy来查看所有可用命令。2.3 关于“Missing JCEF Runtime”错误网络热词中提到了一个错误missing jcef runtime codebuddy relies on jcef (java chromium embedded framework)。这个错误通常发生在尝试运行 CodeBuddy 的桌面独立应用时意味着你的系统缺少必要的 Java Chromium Embedded Framework 运行时环境。解决方案对于 VS Code 扩展用户通常不会遇到此问题因为扩展运行在 VS Code 的上下文中不直接依赖 JCEF。对于独立应用用户你需要根据 CodeBuddy 官方文档的指引下载并安装对应的 JRE (Java Runtime Environment) 或包含 JCEF 的特定运行时包。请务必从官方渠道下载以确保安全。环境就绪后我们就可以进入核心环节定义项目规则。3. 项目规则的核心语法与定义方式CodeBuddy 的项目规则并没有一个全球统一的、像 JSON Schema 那样的严格语法标准其具体实现可能随版本更新但其核心思想是相通的通过自然语言或结构化的指令描述你希望创建的项目蓝图。我们可以将其定义方式归纳为以下几种你可以根据 CodeBuddy 当前版本的支持情况选择使用。3.1 自然语言描述最直接这是最简单的方式。你直接告诉 CodeBuddy 你想要创建什么类型的项目。示例指令“请为我创建一个标准的 Node.js 后端项目使用 Express 框架包含src目录内部有controllers,routes,models,utils子目录、tests目录、一个.gitignore文件忽略 node_modules 和 .env、一个package.json文件包含 express, dotenv, jest 等依赖以及一个基础的app.js入口文件。”CodeBuddy 会解析你的指令并尝试生成对应的文件和结构。这种方式灵活但可能在某些复杂或细节要求上产生偏差。3.2 基于模板更规范你可以先创建一个“规则模板”文件例如一个名为project_rule_template.md或codebuddy_rule.json的文件在其中详细定义规则。然后让 CodeBuddy 读取并执行这个模板。一个规则模板可能包含以下结构以下为概念性示例非官方标准# 项目规则Python FastAPI 后端服务 ## 基本信息 - 项目类型Python Web 后端 - 框架FastAPI - 包管理Poetry (推荐) 或 pip ## 目录结构project-name/ ├── app/ │ ├──init.py │ ├── main.py # FastAPI 应用实例 │ ├── api/ # 路由端点 │ │ ├──init.py │ │ └── v1/ # API 版本 │ │ ├──init.py │ │ ├── endpoints/ │ │ └── models.py │ ├── core/ # 核心配置、安全等 │ ├── schemas/ # Pydantic 模型 │ └── services/ # 业务逻辑 ├── tests/ # 测试目录 ├── alembic/ # 数据库迁移可选 ├── .env.example # 环境变量示例 ├── .gitignore ├── pyproject.toml # Poetry 配置文件 ├── Dockerfile ├── docker-compose.yml └── README.md## 文件内容模板 ### pyproject.toml (Poetry) toml [tool.poetry] name {{project_name}} version 0.1.0 description authors [Your Name youexample.com] [tool.poetry.dependencies] python ^3.9 fastapi ^0.104.0 uvicorn {extras [standard], version ^0.24.0} sqlalchemy ^2.0.0 pydantic ^2.0.0 ... [tool.poetry.group.dev.dependencies] pytest ^7.4.0 black ^23.0.0 isort ^5.12.0 ... [build-system] requires [poetry-core] build-backend poetry.core.masonry.apiapp/main.pyfrom fastapi import FastAPI from app.api.v1 import api_router app FastAPI(title{{project_name}}) app.include_router(api_router, prefix/api/v1) app.get(/) def read_root(): return {Hello: World}后续操作指令运行poetry install安装依赖。复制.env.example为.env并填写配置。使用uvicorn app.main:app --reload启动开发服务器。你可以将这个模板保存然后在需要创建项目时让 CodeBuddy 读取它并替换其中的变量如 {{project_name}}。 ### 3.3 使用 CodeBuddy Skills 组合最强大 这是最接近热词中“项目目录管理agent规则”概念的方式。你可以将创建过程分解为多个步骤每个步骤调用一个特定的 Skill。 **概念性流程** 1. **Skill: CreateDirectory** - 创建根目录和子目录。 2. **Skill: CreateFile** - 创建并初始化 README.md、.gitignore 等文件。 3. **Skill: InitPackageManager** - 初始化 npm init -y 或 poetry init。 4. **Skill: AddDependencies** - 通过命令添加依赖如 npm install express 或 poetry add fastapi。 5. **Skill: WriteTemplateCode** - 根据模板写入初始代码文件。 你可以通过 CodeBuddy 的聊天界面或专用命令顺序执行这些指令或者未来 CodeBuddy 可能会提供可视化的工作流编辑器来编排这些 Skills。 ## 4. 完整实战创建一个 React TypeScript Vite 前端项目规则 现在我们通过一个完整的例子演示如何从零开始利用 CodeBuddy 创建并应用一个前端项目规则。 ### 4.1 定义规则目标 我们要创建一个现代前端项目包含 * 技术栈React 18, TypeScript, Vite * 状态管理Zustand轻量级 * 路由React Router DOM * 代码规范ESLint Prettier 已配置 * 样式Tailwind CSS * 测试Vitest React Testing Library * 标准化文件README.md, .gitignore, .env.example, tsconfig.json, vite.config.ts ### 4.2 与 CodeBuddy 交互执行创建 我们选择使用**自然语言组合指令**的方式分步指导 CodeBuddy。打开 VS Code 的 CodeBuddy 聊天面板。 **第一步创建基础项目结构**在当前位置使用 Vite 官方模板创建一个名为my-react-app的 React TypeScript 项目。命令是npm create vitelatest my-react-app -- --template react-ts*CodeBuddy 可能会直接在你集成的终端中执行此命令或者告诉你如何执行。* **第二步进入项目并初始化基础工具**进入my-react-app目录。然后初始化 ESLint 和 Prettier 并使其兼容运行npm init eslint/configlatest选择适合 ReactTypeScriptVite 的配置。接着安装 Prettier 及相关集成npm install --save-dev prettier eslint-config-prettier eslint-plugin-prettier。最后创建.prettierrc配置文件。**第三步安装额外依赖**安装项目所需的生产依赖和开发依赖生产依赖npm install react-router-dom zustand tailwindcss开发依赖npm install --save-dev types/react-router-dom vitest testing-library/react testing-library/jest-dom jsdom vitejs/plugin-react-swc**第四步配置 Tailwind CSS**初始化 Tailwind CSS运行npx tailwindcss init -p。然后更新生成的tailwind.config.js文件配置 content 源。接着在src/index.css中引入 Tailwind 指令。**第五步创建标准化文件与示例代码**创建.env.example文件包含VITE_API_BASE_URL等示例环境变量。更新README.md填充项目描述、脚本说明。在src目录下创建stores目录并添加一个基础的useCounterStore.ts作为 Zustand 示例。在src目录下创建pages目录添加HomePage.tsx和AboutPage.tsx两个示例页面组件。更新src/App.tsx设置 React Router 的基本路由。在项目根目录创建vite.config.ts配置 Vitest 和 React SWC 插件。**第六步更新 package.json 脚本**在package.json的scripts部分添加test: vitest和coverage: vitest run --coverage等脚本。通过这一系列清晰的指令CodeBuddy 可以协助你完成绝大部分创建工作。你可以将这些指令保存为一个文本文件作为你团队的“React TS 项目规则手册”。 ### 4.3 规则封装与复用进阶 对于需要频繁使用的规则你可以尝试以下进阶方法 1. **创建自定义 CodeBuddy Skill**如果 CodeBuddy 支持高级自定义你可以将上述步骤编写成一个脚本或插件注册为名为 CreateReactTSProject 的 Skill。之后只需一句命令即可触发。 2. **使用 Shell 脚本**将上述所有命令写成一个 Bash 或 PowerShell 脚本如 create-react-ts-app.sh。让 CodeBuddy 执行这个脚本。 bash #!/bin/bash PROJECT_NAME$1 npm create vitelatest $PROJECT_NAME -- --template react-ts cd $PROJECT_NAME # ... 后续所有安装和配置命令 echo 项目 $PROJECT_NAME 创建完成 然后指令简化为“请运行 ./create-react-ts-app.sh my-new-app”。 3. **利用项目模板仓库**最经典的方式是创建一个 Git 模板仓库。然后规则简化为“请克隆 https://github.com/your-org/react-ts-template.git 到 my-new-app并更新项目名称。” CodeBuddy 可以轻松执行 git clone 命令。 ## 5. 常见问题与排查思路 在使用 CodeBuddy 创建项目规则时你可能会遇到一些问题。下表列出了一些常见情况及其解决方法。 | 问题现象 | 可能原因 | 排查与解决思路 | | :--- | :--- | :--- | | **CodeBuddy 未响应或执行命令失败** | 1. API Key 未配置或失效。br2. 网络连接问题。br3. CodeBuddy 服务暂时不可用。br4. 执行的命令在当前环境不存在如未安装 Node.js。 | 1. 检查 VS Code 中 CodeBuddy 插件的状态重新验证 API Key。br2. 检查网络尝试执行一个简单的命令如 echo hello。br3. 查看官方状态页或社区。br4. 在终端手动运行命令确认环境是否准备好。 | | **创建的项目结构不符合预期** | 1. 自然语言描述存在歧义。br2. CodeBuddy 理解有偏差。br3. 规则模板中的路径或变量错误。 | 1. **将指令拆解得更细、更精确**。例如不说“创建 MVC 结构”而说“创建 controllers、models、views 三个目录”。br2. 分步执行每步完成后检查再执行下一步。br3. 仔细检查规则模板文件的语法和路径占位符。 | | **依赖安装失败或版本冲突** | 1. 包管理器npm, pip源问题。br2. 依赖项名称拼写错误。br3. 版本号不兼容。 | 1. 让 CodeBuddy 使用 --registry 参数指定镜像源或手动配置环境。br2. 在指令中提供准确的、最新的包名。br3. 在规则中固定主要依赖的大版本号如 express^4.18.0避免使用 latest。 | | **生成的代码有语法错误** | 1. 代码模板本身有误。br2. 上下文丢失如未先创建依赖的目录。br3. 语言服务如 TypeScript未及时更新。 | 1. 在规则中提供**绝对正确、可运行**的代码片段作为模板。先在小项目中测试模板。br2. 确保指令顺序正确先生成目录结构再生成文件。br3. 创建完成后在 IDE 中手动触发语言服务器重启或重新打开项目。 | | **“Missing JCEF Runtime”错误** | 尝试运行 CodeBuddy 独立桌面应用但缺少 Java 运行时。 | 如非必需建议使用 **VS Code 扩展版**可避免此问题。如需使用桌面版请严格按照官方文档安装所有前置依赖。 | ## 6. 最佳实践与工程建议 将 CodeBuddy 项目规则用于个人或团队遵循以下最佳实践可以最大化其价值。 ### 6.1 规则设计原则 1. **模块化**将大型规则拆分为小的、可复用的步骤或 Skills。例如“初始化 Node.js 项目”、“配置 ESLint”、“添加 Docker 支持”可以作为独立模块。 2. **可配置化**在规则中使用变量如 {{project_name}}、{{port}}使其能适应不同的项目名称和参数。 3. **幂等性**规则执行多次应该产生相同的结果且不会破坏已存在的文件。在脚本中可以使用 if [ ! -d “dir” ]; then mkdir dir; fi 这样的判断。 4. **文档化**为每个规则编写清晰的说明文档解释其目的、生成的结构、包含的技术栈以及后续手动步骤。 ### 6.2 团队协作流程 1. **建立规则仓库**在团队内部 Git 仓库中维护一个 project-templates/ 目录存放各种规则模板文件如 react-ts-rule.md、springboot-rule.md和配套的脚本。 2. **版本化管理**像管理代码一样管理项目规则。当技术栈更新如 React 版本升级时更新规则模板并提交通过 Pull Request 进行评审。 3. **新人入职工具**将标准项目创建规则作为新人入职的第一课。新成员使用 CodeBuddy 执行团队规则能在几分钟内获得一个完全符合规范、可立即开始开发的项目环境极大降低入门门槛。 4. **与 CI/CD 集成**高级可以考虑将规则检查集成到 CI 流程中。例如在 PR 中检查新项目的结构是否由标准规则生成确保一致性。 ### 6.3 安全与维护 1. **敏感信息**规则中**绝对不要**包含真实的 API Key、密码、私钥等敏感信息。使用 .env.example 来提示需要配置哪些环境变量。 2. **依赖安全**定期审查规则中固定的依赖版本更新已知的安全漏洞版本。可以使用 npm audit 或 snyk 等工具。 3. **备份与回滚**在让 CodeBuddy 执行会覆盖现有文件的操作如初始化 Git前确保当前目录不重要或已有备份。 4. **测试规则**在为一个重要项目应用新规则前先在一个临时目录中完整测试一遍整个流程确保所有步骤按预期工作。 通过 CodeBuddy 的项目规则我们能够将项目初始化的经验从个人技巧转化为团队资产。它不仅仅是一个创建工具更是一个**规范执行器**和**知识传播器**。从定义一个清晰的规则开始到将其融入团队的工作流每一步都在提升整个研发团队的效率和代码库的整体质量。虽然目前可能需要通过组合指令或外部脚本来实现复杂规则但随着 AI 助手能力的进化未来可能会有更直观、更强大的可视化规则编辑器出现。现在就开始尝试为你最常创建的项目类型定义一个规则吧你会发现好的开始不仅是成功的一半更能让后续的开发工作事半功倍。
CodeBuddy项目规则：自动化创建标准化项目目录与配置
在开发过程中我们常常面临一个挑战如何高效地管理一个结构清晰、规范统一的项目目录尤其是在团队协作或接手新项目时混乱的目录结构、缺失的配置文件、不统一的依赖管理往往会让开发者花费大量时间在“找文件”和“配环境”上而不是专注于核心业务逻辑。CodeBuddy 作为一款智能的 AI 编程助手其“项目规则”功能正是为了解决这一痛点而生。它能够根据预设的规则自动创建和维护标准化的项目结构确保从项目诞生之初就走在正确的轨道上。本文将深入解析 CodeBuddy 的“创建项目规则”功能。无论你是初次接触 CodeBuddy 的新手还是希望提升团队项目规范性的资深开发者都能从本文中获得一套完整的实操方案。我们将从核心概念讲起逐步深入到规则的定义、配置、实战应用并最终探讨如何将其融入团队的最佳实践。学完后你将能够熟练运用 CodeBuddy 项目规则一键生成结构清晰、配置完备的标准化项目模板。1. 理解 CodeBuddy 项目规则从混乱到秩序在深入技术细节之前我们首先要理解“项目规则”究竟解决了什么问题以及它在 CodeBuddy 生态中扮演的角色。1.1 什么是项目规则简单来说项目规则是一套预定义的、可执行的指令集用于自动化地创建和初始化一个新项目的目录结构、基础文件、依赖配置以及环境设置。你可以把它想象成一个高度智能且可定制的“项目脚手架生成器”。传统上我们可能会手动创建src、tests、docs目录复制粘贴.gitignore、README.md、package.json或pom.xml等文件然后逐一安装依赖。这个过程重复、枯燥且容易出错。CodeBuddy 的项目规则将这一系列操作封装起来你只需要描述或选择规则它就能在瞬间为你搭建好一个“五脏俱全”的项目骨架。1.2 为什么需要它核心价值分析提升启动效率将数分钟甚至更长的初始化时间缩短到几秒钟让开发者能立刻开始编码。保证一致性在团队中强制执行统一的目录结构和开发规范新成员能快速上手减少沟通成本。减少人为错误避免遗漏关键配置文件如.env.example,.dockerignore或配置错误。集成最佳实践可以将安全扫描配置、代码格式化工具Prettier, Black、静态检查ESLint, SonarQube等直接内置到规则中让新项目一开始就具备高质量代码的基因。知识沉淀将团队积累的项目模板经验固化下来形成可复用的资产。1.3 CodeBuddy 项目规则与相关概念区分在搜索热词中我们看到了codebuddy skills、workbuddy等。这里做一个简要区分帮助你更精准地定位“项目规则”CodeBuddy Skills这是 CodeBuddy 的“技能”或“插件”系统。一个“项目规则”本质上可以看作是一个或多个Skills的组合。例如一个“创建 Spring Boot 项目”的规则可能调用了“创建 Maven 项目结构”、“添加 Spring Boot 依赖”、“配置 application.yml”等多个 Skills。CodeBuddy vs WorkBuddy根据网络信息WorkBuddy 可能是另一款侧重于工作流自动化的工具。而 CodeBuddy 更聚焦于代码编写、项目管理和开发辅助。本文讨论的“项目规则”是 CodeBuddy 的核心功能之一。Playwright MCP这可能指的是 CodeBuddy 通过 Model Context Protocol (MCP) 集成 Playwright 进行自动化测试的能力。一个高级的项目规则可以集成此类 Skill在创建项目时自动生成基础的 E2E 测试目录和示例。理解了这些我们就可以开始动手了。2. 环境准备与基础配置在开始定义和使用项目规则之前你需要确保 CodeBuddy 已正确安装并配置。2.1 安装与激活 CodeBuddyCodeBuddy 通常以 IDE 插件如 VS Code 扩展或独立应用程序的形式提供。本文以VS Code 扩展为例这是最常见的使用方式。打开 VS Code。进入扩展市场 (CtrlShiftX 或 CmdShiftX)。搜索CodeBuddy。找到官方扩展并点击“安装”。安装完成后你需要在 CodeBuddy 中配置 API Key 以激活其 AI 能力。这对应了热词中的“vscode中如何通过apikey使用codebuddy”。2.2 配置 API Key在 VS Code 中点击侧边栏的 CodeBuddy 图标通常是一个机器人或特定的 Logo。如果未登录界面会引导你进行注册或登录。登录后找到设置Settings或账户Account相关选项。在 API 配置部分输入你从 CodeBuddy 平台获取的 API Key。注意API Key 是私密信息切勿泄露。通常你可以在 CodeBuddy 的官方网站用户中心找到生成和管理 API Key 的地方。正确配置后CodeBuddy 的聊天界面和命令面板就应该可以正常使用了。你可以通过CtrlShiftP(或CmdShiftP) 打开命令面板输入CodeBuddy来查看所有可用命令。2.3 关于“Missing JCEF Runtime”错误网络热词中提到了一个错误missing jcef runtime codebuddy relies on jcef (java chromium embedded framework)。这个错误通常发生在尝试运行 CodeBuddy 的桌面独立应用时意味着你的系统缺少必要的 Java Chromium Embedded Framework 运行时环境。解决方案对于 VS Code 扩展用户通常不会遇到此问题因为扩展运行在 VS Code 的上下文中不直接依赖 JCEF。对于独立应用用户你需要根据 CodeBuddy 官方文档的指引下载并安装对应的 JRE (Java Runtime Environment) 或包含 JCEF 的特定运行时包。请务必从官方渠道下载以确保安全。环境就绪后我们就可以进入核心环节定义项目规则。3. 项目规则的核心语法与定义方式CodeBuddy 的项目规则并没有一个全球统一的、像 JSON Schema 那样的严格语法标准其具体实现可能随版本更新但其核心思想是相通的通过自然语言或结构化的指令描述你希望创建的项目蓝图。我们可以将其定义方式归纳为以下几种你可以根据 CodeBuddy 当前版本的支持情况选择使用。3.1 自然语言描述最直接这是最简单的方式。你直接告诉 CodeBuddy 你想要创建什么类型的项目。示例指令“请为我创建一个标准的 Node.js 后端项目使用 Express 框架包含src目录内部有controllers,routes,models,utils子目录、tests目录、一个.gitignore文件忽略 node_modules 和 .env、一个package.json文件包含 express, dotenv, jest 等依赖以及一个基础的app.js入口文件。”CodeBuddy 会解析你的指令并尝试生成对应的文件和结构。这种方式灵活但可能在某些复杂或细节要求上产生偏差。3.2 基于模板更规范你可以先创建一个“规则模板”文件例如一个名为project_rule_template.md或codebuddy_rule.json的文件在其中详细定义规则。然后让 CodeBuddy 读取并执行这个模板。一个规则模板可能包含以下结构以下为概念性示例非官方标准# 项目规则Python FastAPI 后端服务 ## 基本信息 - 项目类型Python Web 后端 - 框架FastAPI - 包管理Poetry (推荐) 或 pip ## 目录结构project-name/ ├── app/ │ ├──init.py │ ├── main.py # FastAPI 应用实例 │ ├── api/ # 路由端点 │ │ ├──init.py │ │ └── v1/ # API 版本 │ │ ├──init.py │ │ ├── endpoints/ │ │ └── models.py │ ├── core/ # 核心配置、安全等 │ ├── schemas/ # Pydantic 模型 │ └── services/ # 业务逻辑 ├── tests/ # 测试目录 ├── alembic/ # 数据库迁移可选 ├── .env.example # 环境变量示例 ├── .gitignore ├── pyproject.toml # Poetry 配置文件 ├── Dockerfile ├── docker-compose.yml └── README.md## 文件内容模板 ### pyproject.toml (Poetry) toml [tool.poetry] name {{project_name}} version 0.1.0 description authors [Your Name youexample.com] [tool.poetry.dependencies] python ^3.9 fastapi ^0.104.0 uvicorn {extras [standard], version ^0.24.0} sqlalchemy ^2.0.0 pydantic ^2.0.0 ... [tool.poetry.group.dev.dependencies] pytest ^7.4.0 black ^23.0.0 isort ^5.12.0 ... [build-system] requires [poetry-core] build-backend poetry.core.masonry.apiapp/main.pyfrom fastapi import FastAPI from app.api.v1 import api_router app FastAPI(title{{project_name}}) app.include_router(api_router, prefix/api/v1) app.get(/) def read_root(): return {Hello: World}后续操作指令运行poetry install安装依赖。复制.env.example为.env并填写配置。使用uvicorn app.main:app --reload启动开发服务器。你可以将这个模板保存然后在需要创建项目时让 CodeBuddy 读取它并替换其中的变量如 {{project_name}}。 ### 3.3 使用 CodeBuddy Skills 组合最强大 这是最接近热词中“项目目录管理agent规则”概念的方式。你可以将创建过程分解为多个步骤每个步骤调用一个特定的 Skill。 **概念性流程** 1. **Skill: CreateDirectory** - 创建根目录和子目录。 2. **Skill: CreateFile** - 创建并初始化 README.md、.gitignore 等文件。 3. **Skill: InitPackageManager** - 初始化 npm init -y 或 poetry init。 4. **Skill: AddDependencies** - 通过命令添加依赖如 npm install express 或 poetry add fastapi。 5. **Skill: WriteTemplateCode** - 根据模板写入初始代码文件。 你可以通过 CodeBuddy 的聊天界面或专用命令顺序执行这些指令或者未来 CodeBuddy 可能会提供可视化的工作流编辑器来编排这些 Skills。 ## 4. 完整实战创建一个 React TypeScript Vite 前端项目规则 现在我们通过一个完整的例子演示如何从零开始利用 CodeBuddy 创建并应用一个前端项目规则。 ### 4.1 定义规则目标 我们要创建一个现代前端项目包含 * 技术栈React 18, TypeScript, Vite * 状态管理Zustand轻量级 * 路由React Router DOM * 代码规范ESLint Prettier 已配置 * 样式Tailwind CSS * 测试Vitest React Testing Library * 标准化文件README.md, .gitignore, .env.example, tsconfig.json, vite.config.ts ### 4.2 与 CodeBuddy 交互执行创建 我们选择使用**自然语言组合指令**的方式分步指导 CodeBuddy。打开 VS Code 的 CodeBuddy 聊天面板。 **第一步创建基础项目结构**在当前位置使用 Vite 官方模板创建一个名为my-react-app的 React TypeScript 项目。命令是npm create vitelatest my-react-app -- --template react-ts*CodeBuddy 可能会直接在你集成的终端中执行此命令或者告诉你如何执行。* **第二步进入项目并初始化基础工具**进入my-react-app目录。然后初始化 ESLint 和 Prettier 并使其兼容运行npm init eslint/configlatest选择适合 ReactTypeScriptVite 的配置。接着安装 Prettier 及相关集成npm install --save-dev prettier eslint-config-prettier eslint-plugin-prettier。最后创建.prettierrc配置文件。**第三步安装额外依赖**安装项目所需的生产依赖和开发依赖生产依赖npm install react-router-dom zustand tailwindcss开发依赖npm install --save-dev types/react-router-dom vitest testing-library/react testing-library/jest-dom jsdom vitejs/plugin-react-swc**第四步配置 Tailwind CSS**初始化 Tailwind CSS运行npx tailwindcss init -p。然后更新生成的tailwind.config.js文件配置 content 源。接着在src/index.css中引入 Tailwind 指令。**第五步创建标准化文件与示例代码**创建.env.example文件包含VITE_API_BASE_URL等示例环境变量。更新README.md填充项目描述、脚本说明。在src目录下创建stores目录并添加一个基础的useCounterStore.ts作为 Zustand 示例。在src目录下创建pages目录添加HomePage.tsx和AboutPage.tsx两个示例页面组件。更新src/App.tsx设置 React Router 的基本路由。在项目根目录创建vite.config.ts配置 Vitest 和 React SWC 插件。**第六步更新 package.json 脚本**在package.json的scripts部分添加test: vitest和coverage: vitest run --coverage等脚本。通过这一系列清晰的指令CodeBuddy 可以协助你完成绝大部分创建工作。你可以将这些指令保存为一个文本文件作为你团队的“React TS 项目规则手册”。 ### 4.3 规则封装与复用进阶 对于需要频繁使用的规则你可以尝试以下进阶方法 1. **创建自定义 CodeBuddy Skill**如果 CodeBuddy 支持高级自定义你可以将上述步骤编写成一个脚本或插件注册为名为 CreateReactTSProject 的 Skill。之后只需一句命令即可触发。 2. **使用 Shell 脚本**将上述所有命令写成一个 Bash 或 PowerShell 脚本如 create-react-ts-app.sh。让 CodeBuddy 执行这个脚本。 bash #!/bin/bash PROJECT_NAME$1 npm create vitelatest $PROJECT_NAME -- --template react-ts cd $PROJECT_NAME # ... 后续所有安装和配置命令 echo 项目 $PROJECT_NAME 创建完成 然后指令简化为“请运行 ./create-react-ts-app.sh my-new-app”。 3. **利用项目模板仓库**最经典的方式是创建一个 Git 模板仓库。然后规则简化为“请克隆 https://github.com/your-org/react-ts-template.git 到 my-new-app并更新项目名称。” CodeBuddy 可以轻松执行 git clone 命令。 ## 5. 常见问题与排查思路 在使用 CodeBuddy 创建项目规则时你可能会遇到一些问题。下表列出了一些常见情况及其解决方法。 | 问题现象 | 可能原因 | 排查与解决思路 | | :--- | :--- | :--- | | **CodeBuddy 未响应或执行命令失败** | 1. API Key 未配置或失效。br2. 网络连接问题。br3. CodeBuddy 服务暂时不可用。br4. 执行的命令在当前环境不存在如未安装 Node.js。 | 1. 检查 VS Code 中 CodeBuddy 插件的状态重新验证 API Key。br2. 检查网络尝试执行一个简单的命令如 echo hello。br3. 查看官方状态页或社区。br4. 在终端手动运行命令确认环境是否准备好。 | | **创建的项目结构不符合预期** | 1. 自然语言描述存在歧义。br2. CodeBuddy 理解有偏差。br3. 规则模板中的路径或变量错误。 | 1. **将指令拆解得更细、更精确**。例如不说“创建 MVC 结构”而说“创建 controllers、models、views 三个目录”。br2. 分步执行每步完成后检查再执行下一步。br3. 仔细检查规则模板文件的语法和路径占位符。 | | **依赖安装失败或版本冲突** | 1. 包管理器npm, pip源问题。br2. 依赖项名称拼写错误。br3. 版本号不兼容。 | 1. 让 CodeBuddy 使用 --registry 参数指定镜像源或手动配置环境。br2. 在指令中提供准确的、最新的包名。br3. 在规则中固定主要依赖的大版本号如 express^4.18.0避免使用 latest。 | | **生成的代码有语法错误** | 1. 代码模板本身有误。br2. 上下文丢失如未先创建依赖的目录。br3. 语言服务如 TypeScript未及时更新。 | 1. 在规则中提供**绝对正确、可运行**的代码片段作为模板。先在小项目中测试模板。br2. 确保指令顺序正确先生成目录结构再生成文件。br3. 创建完成后在 IDE 中手动触发语言服务器重启或重新打开项目。 | | **“Missing JCEF Runtime”错误** | 尝试运行 CodeBuddy 独立桌面应用但缺少 Java 运行时。 | 如非必需建议使用 **VS Code 扩展版**可避免此问题。如需使用桌面版请严格按照官方文档安装所有前置依赖。 | ## 6. 最佳实践与工程建议 将 CodeBuddy 项目规则用于个人或团队遵循以下最佳实践可以最大化其价值。 ### 6.1 规则设计原则 1. **模块化**将大型规则拆分为小的、可复用的步骤或 Skills。例如“初始化 Node.js 项目”、“配置 ESLint”、“添加 Docker 支持”可以作为独立模块。 2. **可配置化**在规则中使用变量如 {{project_name}}、{{port}}使其能适应不同的项目名称和参数。 3. **幂等性**规则执行多次应该产生相同的结果且不会破坏已存在的文件。在脚本中可以使用 if [ ! -d “dir” ]; then mkdir dir; fi 这样的判断。 4. **文档化**为每个规则编写清晰的说明文档解释其目的、生成的结构、包含的技术栈以及后续手动步骤。 ### 6.2 团队协作流程 1. **建立规则仓库**在团队内部 Git 仓库中维护一个 project-templates/ 目录存放各种规则模板文件如 react-ts-rule.md、springboot-rule.md和配套的脚本。 2. **版本化管理**像管理代码一样管理项目规则。当技术栈更新如 React 版本升级时更新规则模板并提交通过 Pull Request 进行评审。 3. **新人入职工具**将标准项目创建规则作为新人入职的第一课。新成员使用 CodeBuddy 执行团队规则能在几分钟内获得一个完全符合规范、可立即开始开发的项目环境极大降低入门门槛。 4. **与 CI/CD 集成**高级可以考虑将规则检查集成到 CI 流程中。例如在 PR 中检查新项目的结构是否由标准规则生成确保一致性。 ### 6.3 安全与维护 1. **敏感信息**规则中**绝对不要**包含真实的 API Key、密码、私钥等敏感信息。使用 .env.example 来提示需要配置哪些环境变量。 2. **依赖安全**定期审查规则中固定的依赖版本更新已知的安全漏洞版本。可以使用 npm audit 或 snyk 等工具。 3. **备份与回滚**在让 CodeBuddy 执行会覆盖现有文件的操作如初始化 Git前确保当前目录不重要或已有备份。 4. **测试规则**在为一个重要项目应用新规则前先在一个临时目录中完整测试一遍整个流程确保所有步骤按预期工作。 通过 CodeBuddy 的项目规则我们能够将项目初始化的经验从个人技巧转化为团队资产。它不仅仅是一个创建工具更是一个**规范执行器**和**知识传播器**。从定义一个清晰的规则开始到将其融入团队的工作流每一步都在提升整个研发团队的效率和代码库的整体质量。虽然目前可能需要通过组合指令或外部脚本来实现复杂规则但随着 AI 助手能力的进化未来可能会有更直观、更强大的可视化规则编辑器出现。现在就开始尝试为你最常创建的项目类型定义一个规则吧你会发现好的开始不仅是成功的一半更能让后续的开发工作事半功倍。