4.2 KiB
4.2 KiB
变更历史
| 日期 | 变更人 | 变更内容 |
|---|---|---|
| 2026-04-30 | Atlas | 补充“变更历史”章节（文档治理） |
1. 项目概览（Project Overview）
用 2-3 句话说清楚这是什么项目、核心用途、目标用户。AI 需要这个"北极星"来判断所有技术取舍。
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
## 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
## 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
## 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
## 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
## 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
## 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
## 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
> **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 都会做出你不想要的选择。