161 lines
4.0 KiB
Markdown
161 lines
4.0 KiB
Markdown
#### 1. 项目概览（Project Overview）
|
||
|
||
用 2-3 句话说清楚这是什么项目、核心用途、目标用户。AI 需要这个"北极星"来判断所有技术取舍。
|
||
|
||
md
|
||
|
||
```md
|
||
## Project Overview
|
||
A B2B SaaS invoice management tool. Target users are SMB accountants.
|
||
Prioritize reliability and data integrity over flashy UI.
|
||
```
|
||
|
||
---
|
||
|
||
#### 2. 核心技术栈（Core Stack）
|
||
|
||
每一层都要写清楚，**不要只写框架名，要写版本号和选型原因**。
|
||
|
||
md
|
||
|
||
```md
|
||
## Core Stack
|
||
- Runtime: Node.js 22 (not Bun, not Deno)
|
||
- Framework: Next.js 15 (App Router only, never Pages Router)
|
||
- Language: TypeScript 5.x, strict mode enabled
|
||
- Database: PostgreSQL 16 via Supabase
|
||
- ORM: Drizzle ORM (not Prisma)
|
||
- Styling: Tailwind CSS v4 + shadcn/ui
|
||
- Auth: Clerk
|
||
- Deployment: Vercel
|
||
```
|
||
|
||
---
|
||
|
||
#### 3. 关键约定（Key Conventions）
|
||
|
||
这是 vibe coding 最容易出错的地方，AI 会有自己的"默认习惯"，必须显式覆盖。
|
||
|
||
md
|
||
|
||
```md
|
||
## Key Conventions
|
||
- File naming: kebab-case for files, PascalCase for components
|
||
- All server actions in /actions, never inline in components
|
||
- Use `server components` by default; add 'use client' only when needed
|
||
- Environment variables: never hardcode, always use process.env.NEXT_PUBLIC_*
|
||
- Error handling: always use Result pattern, never throw in server actions
|
||
- No `any` types. No `// @ts-ignore`.
|
||
```
|
||
|
||
---
|
||
|
||
#### 4. 目录结构（Directory Structure）
|
||
|
||
AI 需要知道把新文件放在哪里，否则它会自己"发明"结构。
|
||
|
||
md
|
||
|
||
```md
|
||
## Directory Structure
|
||
src/
|
||
├── app/ # Next.js routes only, minimal logic
|
||
├── components/ # Reusable UI components
|
||
│ └── ui/ # shadcn primitives, DO NOT edit
|
||
├── actions/ # Server actions
|
||
├── lib/ # Utilities and helpers
|
||
├── db/ # Drizzle schema and migrations
|
||
└── types/ # Global TypeScript types
|
||
```
|
||
|
||
---
|
||
|
||
#### 5. 明确禁止的东西（Explicitly Forbidden）
|
||
|
||
这是最被忽视但最重要的部分。告诉 AI **不要用什么**，比告诉它用什么更有效。
|
||
|
||
md
|
||
|
||
```md
|
||
## Do NOT Use
|
||
- ❌ `axios` — use native `fetch`
|
||
- ❌ `moment.js` — use `date-fns`
|
||
- ❌ `useEffect` for data fetching — use server components or React Query
|
||
- ❌ `pages/` directory — App Router only
|
||
- ❌ `class components` — functional only
|
||
- ❌ CSS Modules or styled-components — Tailwind only
|
||
- ❌ `console.log` in production code
|
||
```
|
||
|
||
---
|
||
|
||
#### 6. 第三方服务与集成（External Services）
|
||
|
||
列出已经接入的服务，避免 AI 重复造轮子或引入冲突的 SDK。
|
||
|
||
md
|
||
|
||
```md
|
||
## External Services
|
||
- Payments: Stripe (already configured in /lib/stripe.ts)
|
||
- Email: Resend + React Email templates
|
||
- File storage: Supabase Storage (not S3)
|
||
- Analytics: PostHog
|
||
- Error tracking: Sentry
|
||
```
|
||
|
||
---
|
||
|
||
#### 7. 代码风格与 Linting（Code Style）
|
||
|
||
md
|
||
|
||
```md
|
||
## Code Style
|
||
- Formatter: Prettier (config in .prettierrc)
|
||
- Linter: ESLint with eslint-config-next
|
||
- Imports: absolute paths via `@/` alias, no relative `../../`
|
||
- Prefer `const` over `let`, avoid `var`
|
||
- Async/await over `.then()` chains
|
||
```
|
||
|
||
---
|
||
|
||
#### 8. 测试策略（Testing, 如果有的话）
|
||
|
||
md
|
||
|
||
```md
|
||
## Testing
|
||
- Unit tests: Vitest
|
||
- E2E tests: Playwright (critical flows only)
|
||
- No snapshot tests
|
||
- Test files co-located: `component.test.ts` next to `component.ts`
|
||
```
|
||
|
||
---
|
||
|
||
### 一个实用的小技巧
|
||
|
||
在文件开头加一句 AI 专用说明：
|
||
|
||
md
|
||
|
||
```md
|
||
> **For AI assistants**: Read this entire file before writing any code.
|
||
> All decisions here are final. Do not suggest alternatives unless asked.
|
||
```
|
||
|
||
---
|
||
|
||
### 内容优先级总结
|
||
|
||
|优先级|内容|原因|
|
||
|---|---|---|
|
||
|🔴 必须|核心技术栈 + 禁止列表|防止 AI 用错库|
|
||
|🔴 必须|目录结构 + 文件约定|防止结构混乱|
|
||
|🟡 重要|外部服务清单|防止重复实现|
|
||
|🟡 重要|关键约定|保持风格一致|
|
||
|🟢 加分|测试策略 + 代码风格|提升整体质量|
|
||
|
||
**核心原则**：写给 AI 看的文档要比写给人看的**更具体、更强硬、更少歧义**。任何"视情况而定"的描述，AI 都会做出你不想要的选择。 |