SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场windsurf-reference-architecture

windsurf-reference-architecture

编程与开发

查看项目

更新于 10-16 09:10

技能介绍

Windsurf Reference Architecture 是一套面向 Windsurf AI 的完整项目架构方案，覆盖工作区配置、规则层级、工作流组织与团队标准化模式，目标是最大化 Cascade 的效用。

用途

该技能用于为 Windsurf IDE 设计与实现参考架构，帮助团队在项目层面统一 AI 上下文、规则与自动化流程。使用前提包括：已安装 Windsurf IDE；团队就编码标准达成一致；仓库具备一致的项目结构。

架构组成

架构图展示了四层结构：

  1. Windsurf 工作区：包含 .windsurfrules（AI 上下文）、.windsurf/ 目录（rules 触发规则、workflows 自动化、settings.json）、.codeiumignore（索引排除规则），以及用户级的 ~/.codeium/（global_rules.md、windsurf/memories/、windsurf/mcp_config）。
  2. Cascade AI 引擎：包括 Supercomplete（Tab）、Cascade Write/Chat（Cmd+L）、Command 内联编辑（Cmd+I）。
  3. 上下文层：优先级为 Rules > Memories > @Mentions > Open Files > Index。

主要能力与使用方式

Step 1 项目文件结构：在项目根目录设置 .windsurfrules、.codeiumignore、.windsurf/settings.json、.windsurf/rules/（如 testing.md 触发 glob /*.test.ts、api-routes.md 触发 src/routes/、security.md 触发 model_decision、migrations.md 手动触发）以及 .windsurf/workflows/（如 /new-feature、/deploy-staging、/review-pr、/quality-check），并配合 src/（routes、services、repositories、types）、tests/（fixtures、services）、docs/architecture.md 的目录组织。

Step 2 规则层级（优先级由高到低）：

  • 全局规则：路径 ~/.windsurf/global_rules.md，上限 6000 字符，作用于所有工作区，用于个人偏好与通用标准。
  • 项目 .windsurfrules：项目根目录，上限 6000 字符，作用于当前工作区，用于项目技术栈、架构与约定。
  • 工作区规则：.windsurf/rules/*.md，每个上限 12000 字符，由 glob、model_decision 或手动触发，用于按文件类型的模式与条件规则。
  • Memories：~/.codeium/windsurf/memories/，按工作区自动生成，用于补充决策与发现，不替代规则。
  • 说明指出全局与工作区规则合计最多 12000 字符；超出时全局规则优先，工作区规则被截断。

Step 3 团队配置模板：提供可提交到 git 的 .windsurf/settings.json 示例，包含 codeium.indexing.excludePatterns（node_modules/、dist/、.next/、coverage/、.min.js、**/.map）、codeium.autocomplete.enable、editor.formatOnSave、editor.defaultFormatter（biomejs.biome）、typescript.tsdk 与 files.associations 等设置。

Step 4 Monorepo 策略：根目录放共享且简短的 .windsurfrules 与宽泛的 .codeiumignore，各子项目（apps/web、apps/mobile、packages/api、packages/shared）各自维护 .windsurfrules，.windsurf/workflows/ 存放跨包工作流。最佳实践是直接打开 apps/web/ 或 packages/api/，而非 monorepo 根目录，以便每个工作区窗口获得聚焦上下文。

Step 5 上下文固定策略：建议固定类型定义文件、架构决策记录、API schema 文件、数据库 schema 等；通过 Cascade 上下文区域文件旁的固定图标操作，固定文件始终进入上下文窗口，建议最多固定 3–5 个文件，过多会稀释上下文。

错误处理

文档列出常见问题与解决方式：Cascade 忽略项目模式（缺少或空的 .windsurfrules，需补充技术栈与架构细节）；规则被截断（合计超过 12000 字符，需拆分为带触发条件的工作区规则）；文件类型模式不匹配（缺少 glob 触发规则，需在 .windsurf/rules/ 添加 glob 触发）；团队不一致（无共享配置，需将 .windsurf/ 提交到 git）；monorepo 索引缓慢（打开的是根工作区，应打开具体包或应用目录）。

示例

提供最小 .windsurfrules 模板（项目名、技术栈、测试框架、3–5 条关键编码模式、2–3 条显式反模式），以及一段验证架构设置的 shell 脚本，用于检查 .windsurfrules 字符数、.codeiumignore 规则数、规则目录与工作流文件数量。

限制与未提供信息

该资料未提供具体的计费、价格、平台版本或性能数据；相关事实暂未提供。使用效果取决于团队是否统一执行配置与标准。