约束 Next.js App Router 项目的全局代码结构规范。当用户要求创建页面、组件、hooks、类型定义、工具函数、状态管理、常量配置时触发。强制所有代码归入正确的全局目录(/components、/types、/hooks、/lib、/constants、/stores),禁止在 page.tsx 中内联逻辑、禁止使用 _components 局部目录、禁止类型散落在各路由文件内。适用于任何涉及新建或修改 .tsx/.ts 文件的任务。
project-root/
├── app/ # 仅放路由文件
│ ├── (marketing)/
│ │ └── page.tsx # 只做组装
│ ├── doc/
│ │ ├── page.tsx
│ │ └── layout.tsx
│ └── layout.tsx
│
├── components/ # 所有组件,按领域分子目录
│ ├── ui/ # ShadCN 通用组件(Button, Badge, Input...)
│ ├── layout/ # 布局组件(Header, Footer, Sidebar...)
│ ├── doc/ # 文档页专用组件
│ ├── marketing/ # 营销页专用组件
│ └── shared/ # 跨领域共享组件
│
├── types/ # 所有类型定义,按领域分文件
│ ├── doc.ts
│ ├── user.ts
│ └── api.ts
│
├── hooks/ # 所有 custom hooks
│ ├── useAuth.ts
│ ├── useDoc.ts
│ └── useSearch.ts
│
├── lib/ # 工具函数、第三方封装
│ ├── utils.ts
│ ├── fetcher.ts
│ └── mdx.ts
│
├── constants/ # 静态配置、枚举值、导航数据等
│ ├── nav.ts
│ └── config.ts
│
└── stores/ # 状态管理(zustand / jotai 等)
├── userStore.ts
└── docStore.ts
_components/ 局部目录,所有组件进 /components/<领域>//components 内部必须按业务领域建子目录,禁止所有组件平铺在根层type / interface 定义进 /types/<领域>.ts,不允许写在 page.tsx 或组件文件内/hooks/,不允许写在组件文件内部/constants/npx biome checkseverity: error 的条目交付// ✅ 正确的 page.tsx
import { DocSidebar } from '@/components/doc/DocSidebar'
import { DocContent } from '@/components/doc/DocContent'
import { getDocData } from '@/lib/doc'
import type { DocPageProps } from '@/types/doc'
export default async function DocPage({ params }: DocPageProps) {
const data = await getDocData(params.slug)
return (
<div className="flex">
<DocSidebar />
<DocContent data={data} />
</div>
)
}
// ❌ 禁止——类型、数据、多组件全部塞进 page.tsx
type NavItem = { id: string; title: string }
const NAV_ITEMS: NavItem[] = [...]
function Sidebar() { ... }
function Content() { ... }
export default function DocPage() { ... }
// ✅ 类型放 /types/doc.ts
export interface DocPageProps {
params: { slug: string }
}
export interface DocItem {
id: string
title: string
content: string
}
// ✅ 静态数据放 /constants/nav.ts
export const DOC_NAV = [
{ id: 'intro', title: '介绍', href: '/doc/intro' },
// ...
] as const
npx biome check --write . 自动修复格式,再 npx biome check . 确认无 error# 查看当前项目全局目录结构(2 层)
find . -maxdepth 2 -type d | grep -v node_modules | grep -v .git | sort
# 找出超过 150 行的组件(需要拆分的候选)
find components -name "*.tsx" | xargs wc -l | sort -rn | head -20
# Biome 检查 + 自动修复
npx biome check --write .
npx biome check .