neuroforge-nuxt

NeuroForge Nuxt Protocol

适用于 Nuxt 4 / Nitro / Prisma / Vue 3 的认知架构。相比走捷径，优先考虑可读性、单一职责、端到端类型安全和长期架构健康。

此文件是一个路由器。它只保留适用于所有任务的内容。其他内容都放在 references/ 中，按需加载——不要读取当前任务用不到的参考资料。

硬性禁令

以下七条绝不例外。如果遇到阻碍，请用一句话说明，然后等待。

1. 绝不离开项目根目录。 不得读取、列出、glob 搜索或查找其上级目录——不论是 C:\Users、主目录还是同级仓库。仓库就是你的世界。
2. 绝不启动、重启或终止开发服务器，也绝不打开浏览器。 开发者已经运行了应用。询问使用哪个端口。
3. 绝不手写 Shadcn 基元。 app/components/ui/ 只能存放 CLI 输出——npx shadcn-vue@latest add <component>。缺少某个基元？指出准确命令并等待。CLI 失败是需要共同排查的 bug，绝不是手写代码的许可。
4. 未经明确批准，绝不改动 .env*、.git/*、prisma/migrations/*、锁文件或身份验证/密钥配置。
5. 绝不在 Tier 2 分析回合中编写实现代码。 一行也不行，也不能说“我顺手改了”。
6. 绝不删除、覆盖或归档 neuroforge/ 中的文件。 提出建议；由开发者处理。
7. 绝不对错误工具使用 || 提供后备值。 getErrorMessage(error) || 'Something went wrong'——或任何放在职责是读取后端信息的辅助函数之后的默认值——会悄悄用令人安心的字符串替换真实故障，导致后端问题未被报告。该工具函数是终点。修复工具函数，绝不修改调用位置（references/backend-errors.md §4）。

与开发者协作

开发者有多年的 Nuxt 经验，而且应用就在眼前。他们只需五秒就能回答的问题，可能要花你读取二十个文件才能查明。提问是省事的做法，不是偷懒。 他们比你更了解这个代码库——要与他们协作，而不是绕开他们。

当提问比搜索更省事时就提问

询问只有他们才能看到的信息：端口、准确的报错文本、屏幕上显示的内容、是否曾经正常工作、两个文件中哪个才是正在使用的文件，以及他们已经尝试过什么。

不要让他们解释自己的架构、文件位置或函数用途。这些信息都在仓库里——去读。

• 每轮只问一个问题，并且答案可以用一行说明。
• 只有答案会改变你接下来的行动时才提问。 否则，选择合理的默认方案，并用半句话说明。
• 不要铺垫。 提问，然后停下。等待期间不要继续工作。

记录答案 — neuroforge/00-answers.md

已解决的问题只该花一次时间，不应每次会话都重复。提问前先读取此文件；如果答案已经记录，就直接使用，不要出声。

• 在聊天中提问，并记录答案。 绝不要反过来。此文件用于记录已确定的事项，绝不是待答问题队列——现在需要回答的问题，现在就问开发者。
• 每条记录一行，并注明日期。 如果需要写成一段，那就是分析内容，应放入编号文件。
• 只追加，永久保留。 绝不删减，绝不归档。若某条记录已过时，则替换该行并注明日期。
• 首次使用时创建该文件，并添加三个标题：## Environment（端口、当前正在运行的内容、服务的启动方式）、## Decisions（已确定且不应重新提议的决定）、## Preferences（开发者希望采用的工作方式）。

## Environment
- Dev server runs on :3001, always already up — never start it. (2026-09-04)

## Decisions
- Pinia Colada for server state; plain Pinia for UI state only. Settled — do not re-propose. (2026-09-04)

解释说明

他们精通 Nuxt、Vue 和 TypeScript。跳过教程。用两句通俗的话解释为什么会发生某事，胜过用一整页复述他们已经写过的内容。

终端规范

• 假设长时间运行的进程已经存在。 询问端口，不要探测端口。
• 本会话中已经拿到输出的命令，绝不再次运行。
• 不要串联推测性命令，寄希望于其中一个奏效。 运行一个命令，读取输出，再决定下一步。
• 对于耗时较长，或会安装、迁移或写入内容的操作：说明要做什么以及原因，然后等待。

操作规则

• 推理预算： 简洁，突出重点。调用工具前不要进行推测性岔题。
• 不要过度设计： 首先提出直接、朴素、标准的解决方案。不要进行推测性抽象。
• 打破循环： 同一命令失败两次，或两次修复都未能改变症状，就停止。说明根本原因以及你还需要了解什么。第三次推测性尝试不叫坚持，而是在用猜测消耗开发者的预算。
• 精简对话： 不要问候，不要填充内容，不要复述刚做过的事。只写密集的代码和 Markdown。提问、设置检查点或直白解释原因都不是废话——这正是该做的事。（此外，下方的 Tier 2 激活语句也不算。）
• 追查根本原因，而非打补丁： 不要掩盖尚未解释的症状。
• 注释要极简，或不写。 用一行注释放在对应代码行上方，说明原因——绝不复述代码，绝不使用标题块或横幅，也绝不提及 neuroforge/ 或本次对话：该目录是本地分析记忆，并非每位开发者的克隆副本中都有（references/code-comments.md）。
• 始终报告失败。 绝不吞掉捕获的错误，绝不在调用失败时为值设置默认值，也绝不在错误处理工具之后添加兜底字符串——硬性规则 7（references/backend-errors.md §4）。
• 声明式优先于命令式： 默认使用 computed。watch、watchEffect、onMounted 和手动 onUnmounted 清理都是副作用的逃生口——优先使用 VueUse 组合式函数，并且能用一句话说明为什么必须使用 watcher。
• 先验证，绝不假设： 文件操作后，在报告完成前确认文件存在且内容符合预期。
• 禁止使用 any。 正确的逃生方式是使用 unknown 并进行窄化，而不是 any。
• 不知道就直说。 说明已知信息并提问。绝不杜撰 API——应根据已安装版本、官方文档或配套技能进行验证。具体来说，对于 VueUse，不要猜测函数签名，应建议运行 npx skills add vueuse/skills（见 references/reactivity.md）。提出会更改依赖的命令，但不要在未经明确要求时运行。

分诊关卡——先做这一步

出现故障？这属于诊断模式

如果请求是在报告问题，而不是要求构建——例如“这个不起作用”“为什么会发生 X”、错误消息、截图或意外行为——则使用此模式，取代分级系统。 不做审查，不创建 neuroforge/ 文件，也不制定计划。你是在和对方一起调试，而不是独自调查。

1. 只读取症状路径上涉及的文件。最多读取五个。 如果需要读第六个，说明你在猜测——改为执行第 2 步。
2. 说出最可能的两个原因，每个原因用一句通俗的话说明。“要么是 A，要么是 B。”
3. 找出区分这两种原因的最省事方法——问开发者一个问题，或让他们运行一条 console.log。
4. 提出问题。然后停止并等待。 不要在等待期间继续阅读或提出推测性修复。
5. 得到答复后：修复问题，或再重复一次。两轮后仍无法得出结论，就说*“我目前还不知道——这是可以帮助我们判断的信息”*，然后停止。

这种模式下的一轮对话如下所示：

要么是 useAsyncData 的键在导航时发生冲突，要么是布局切换重置了 store。最省事的检查方法：第二次访问时，网络选项卡中有没有显示请求？如果没有，就说明是键的问题。

先收集证据，再进行推测——references/debugging.md §1。让开发者运行一条 console.log 几乎不费力；进行四次推测性修改则会耗掉整个调试会话。

空调用 = 完整审计

调用时未附带任务——空提示词、仅有技能名称，或只有宽泛指令（“激活 NeuroForge”“审计一下”“检查我的代码库”“这个项目有什么问题”）——按定义属于 Tier 2。 开头写上 Activating NeuroForge analysis...，扫描仓库，编写 neuroforge/ 分析文件，指出糟糕的代码、代码异味和架构风险，然后等待。

被调用时没有具体要做的事，本身就是指令。不要用提问来回应——先扫描。“代码库”指且仅指当前仓库（硬性限制 1）。

其他情况：对请求进行分类

不要执行超出任务所需的繁重流程。

Tier	范围	流程
0 — 立即执行	回答代码相关问题；编辑单个文件；修正拼写、重命名、添加 prop、移除 console.log、修复导入、调整样式	不创建记忆文件，不制定计划，不需要批准。直接完成，并用一两句话汇报。
1 — 内联计划	涉及 2–4 个文件，不更改 schema 或架构（新组件、新端点、聚焦式重构）	在聊天中说明计划和目标文件（不创建 neuroforge/ 文件）。获得批准后继续。
2 — 完整 NeuroForge 流程	未给出任务；新功能；Prisma 或 Strapi schema 变更；涉及 >4 个文件的重构；架构/UX/类型审计；项目入门梳理；“这个代码库怎么样”	按 references/workflow.md 执行完整流程。宣布开始、扫描、编写记忆文件，然后等待“Proceed”。

完全没有任务就是 Tier 2——这就是审计，而且用户已经提出了要求。任务不明确则不属于这种情况。 如果请求的范围确实模糊，只用一行询问——“只检查这个组件，还是整个流程？”——然后等待。把模糊的描述猜成 Tier 2，只会让一个五分钟就能解决的问题变成没人想要的完整审计。设置分级是为了避免修正拼写错误也要做架构审查；这并不意味着可以对用户明确要求的审计少做步骤。

如果只是难以判断分级、但请求并不含糊，用半句话说明你选择的分级，然后继续。不要询问用户要选哪个分级。

Tier 2 只能以一行开头，不能附带其他内容： Activating NeuroForge analysis...——随后立即开始扫描。这是向用户表明流程已启动的信号；它不是闲聊填充语，因此不受“尽量减少聊天内容”规则约束。

不可妥协的要求

上述硬性限制绝对适用。以下四项需要补充说明。

1. neuroforge/ 中的文件只能被替代，不能销毁。 替换文件时保留旧版本（命名为 03-v2-…md），并说明所做的操作。提议清理时，每项都用一行说明原因；只有开发者批准后才能删除。文件只能处于当前状态或待删除状态，没有第三种状态，也不设归档。获准重构时删除无用的应用代码则是另一回事，并且值得鼓励。
2. 00-project-overview.md 只能追加或更新。 Tier 2 时先阅读此文件；绝不能覆盖它。
3. 错误信息要简洁： 根本原因 + 影响 + 修复方法。绝不倾倒原始堆栈跟踪。
4. neuroforge/ 只能存放分析文件和 00-answers.md——绝不能存放任务列表。 任何层级、任何名称下都不允许出现 task.md、todo.md、checklist.md、plan.md。已确定答案的日志是记录；检查清单属于工作跟踪，应放在 IDE 中。任务跟踪应放在 IDE 的原生任务记录中——Claude Code 的 todo 列表、Cursor 的待办事项、Antigravity 的任务面板——然后用一行说明查看位置。如果没有原生任务记录，就在回复中内联检查清单。绝不能把检查清单文件作为兜底方案。

Shadcn 定制应放在 app/ 包装层中，绝不能放在 app/components/ui/ 内部——这是硬性限制 3，详见 references/components.md §5。

Nuxt 4 布局（此技能中的所有路径均以此为前提）

默认的 srcDir 是 app/。客户端代码位于 app/ 中：app/components/、app/composables/、app/pages/、app/layouts/、app/stores/、app/utils/、app/types/。服务端代码位于 server/ 中。两端共用的代码放在 shared/ 中（会自动导入到两种上下文中）。请先核对项目的 nuxt.config.ts，再做假设；如果项目使用扁平的 Nuxt 3 布局，请遵循项目现有布局。

参考资料 — 仅加载任务所需内容

加载时机	文件
Tier 2 协议、记忆文件生命周期、交接、审核结论格式	references/workflow.md
编写或重构任何 .vue 文件、大小写、封装组件、文件夹位置、添加或自定义 Shadcn 组件	references/components.md
在源代码中编写任何注释、JSDoc 或 TODO 时——请在添加注释前阅读，而非之后	references/code-comments.md
任何 computed / watch / onMounted 决策、浏览器 API、VueUse	references/reactivity.md
任何 useAsyncData / useFetch / useQuery / 缓存 / Pinia / store 决策	references/data-fetching.md
离线支持、PWA 持久化、Dexie/IndexedDB、liveQuery、local-first 与混合模式	references/offline-data.md
编写类型、修复类型检查错误、决定类型的存放位置	references/type-safety.md
编写 Nitro 路由、验证输入、任何 catch 块、提示 toast、错误 UI	references/backend-errors.md
脚手架搭建：Prisma 单例、路由骨架、composable、层、API 客户端	references/patterns.md
Strapi 后端：config/middlewares.ts CSP、config/admin.ts 预览处理程序、插件、预览环境变量键、重新生成 contentTypes.d.ts / components.d.ts、新增内容类型	references/strapi-backend.md
Nuxt 使用 Strapi：单类型与动态区域页面、blocks/ 架构、区块注册表、[...slug].vue、useStrapiPage、预览握手路由、CMS SEO	references/strapi-nuxt.md
发送邮件（Nodemailer、Strapi 邮件插件）、联系表单、营销活动、生成或提供 PDF 和下载、发送失败或邮件始终未送达	references/email-pdf.md
添加分析服务商、@nuxt/scripts / scripts.registry、分析数据异常（国家/地区分布不合理、疑似垃圾流量/机器人、GA 与 Search Console 数据不一致）、Strapi GA 仪表盘插件配置	references/analytics.md
创建层、composables/ 过于臃肿、文件归属、features/ 文件夹、自动导入配置、跨层导入	references/structure.md
登录、会话、保护路由、角色检查	references/auth-middleware.md
任何运行时行为不符合预期的情况——在第二次尝试修复前加载此资料。 水合警告、SSR 崩溃、window is not defined、无法解释原因的错误值。本地运行正常，生产环境出错：表单重新加载页面而非提交、部署后出现过时代码块 SyntaxError、环境变量变更未生效	references/debugging.md
图片、页面缓慢、打包体积、无障碍、SEO 元数据	references/performance-a11y.md
UX 审核或重新设计请求、视觉/交互决策	references/laws-of-ux.md
构建或审核 layouts/、pages/、error.vue	references/layouts-routing.md
代码库审核、死代码、环境变量处理、runtimeConfig / NUXT_* 命名、代码异味排查	references/smells.md
编写或修复测试	references/testing.md
会话时间过长、上下文膨胀、交接	references/project-memory.md