project-architecture

项目架构准则

激活约定

在修改 Next.js 或 Astro 应用的 UI、布局、组件结构、状态流、主题、数据显示或服务端/客户端边界之前，先加载此技能。

硬性规则

1. 操作前先从项目中检测框架；绝不假设框架。
2. 优先采用服务端渲染。只有交互无法在没有客户端代码的情况下运行时，才添加客户端代码，并尽可能缩小其范围。
3. 修改框架 API 或项目结构前，先阅读已安装框架的官方文档。
4. 如果存在 DESIGN.md，视觉和 UX 决策应遵循其中的要求。
5. 编写自定义标记或样式前，先使用现有的 shadcn 原语和语义化令牌；如果已安装 shadcn-component-boundaries，则加载该工具。
6. 为每个数据显示明确提供加载、空数据和错误状态。
7. 根据风险添加相应测试，并使用项目已有的测试工具。

决策门槛

项目信号	框架	指南
package.json 依赖中包含 next，或存在 next.config.* 文件	Next.js	references/next.md
package.json 依赖中包含 astro，或存在 astro.config.* 文件	Astro	references/astro.md
两者都有或都没有	未知	停下并询问本次修改针对哪个应用

执行步骤

1. 阅读 package.json 并列出根目录配置文件，以检测框架。
2. 加载对应的参考文档并应用其中的边界规则。
3. 创建新组件前，先搜索现有组件、路由和样式。
4. 以可行的最小客户端代码范围实现修改。
5. 完成修改前检查清单，然后在已安装 project-min-evaluation 时加载它，否则运行项目的质量检查脚本。

修改前检查清单：

• 是否添加了不必要的客户端代码？
• 是否遵循了 DESIGN.md？
• 是否明确提供了加载、空数据和错误状态？

输出约定

报告检测到的框架、所有新增或移动的服务端/客户端边界（及其原因），以及检查清单的答案。

参考文档

• references/next.md — Next.js 服务端/客户端边界规则。
• references/astro.md — Astro 岛屿边界规则。