隨記

專案規範撰寫指南

如何撰寫 AGENTS.md / CLAUDE.md 讓 AI Agent 理解你的專案

原則

  1. 簡潔：只寫這個專案的特殊規則
  2. 具體：給出明確的指令，不是模糊的原則
  3. 可執行：AI 能直接照做

AGENTS.md 結構

# Project Guidelines

## Tech Stack
- Framework: Angular 19
- Language: TypeScript
- Styling: Tailwind CSS
- Backend: Tauri + Rust

## Directory Structure
- `src/app/components/` — UI Components
- `src/app/services/` — Business Logic
- `src-tauri/src/` — Rust Backend

## Coding Conventions
- Use standalone components
- Use signals for state management
- Use snake_case for Rust/SQLite fields
- Components should be < 200 lines

## Architecture
- Clean Architecture (Domain → Application → Infrastructure → Presentation)
- Domain layer: no external dependencies
- Use Cases: orchestrate business logic
- Repository pattern for data access

## Testing
- Unit tests for Use Cases
- Component tests for UI
- Run `npm test` before commit

## Common Commands
- `npm run build` — Build Angular
- `cargo build` — Build Rust
- `npm test` — Run tests

範例：不同專案類型

前端專案

## Tech Stack
- React 18 + TypeScript
- Vite + Tailwind CSS

## Conventions
- Functional components only
- Use hooks for state
- Props interface must be exported
- CSS: Tailwind utility classes only

## File Naming
- Components: `PascalCase.tsx`
- Utils: `camelCase.ts`
- Types: `types.ts`

後端專案

## Tech Stack
- Node.js + Express
- PostgreSQL + Prisma

## Conventions
- REST API with versioning (`/api/v1/...`)
- Error handling: custom error classes
- Validation: Zod schemas

## Architecture
- Controller → Service → Repository
- Controller: handle HTTP
- Service: business logic
- Repository: database access

全端專案

## Structure
- `frontend/` — Angular app
- `backend/` — Node.js API
- `shared/` — Shared types

## Conventions
- Shared types in `shared/types.ts`
- API contract: OpenAPI spec
- Both sides must pass typecheck

常見錯誤

❌ 太長：把整本教科書貼進去
❌ 太籠統：「寫好 code」
❌ 太過時：規範與實際不符
❌ 太嚴格：限制 AI 創造力

維護建議

1. 定期更新（每月）
2. 跟著專案演進
3. 團隊共同維護
4. 版本控制