## 变更历史

| 日期 | 变更人 | 变更内容 |
|---|---|---|
| 2026-04-30 | Atlas | 补充“变更历史”章节（文档治理） |

#### 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 都会做出你不想要的选择。