docs: 生成层次化 AGENTS.md 文档系统

src/lib/AGENTS.md

@@ -0,0 +1,66 @@
+# src/lib/ - Core Utilities
+
+## Overview
+
+Shared utilities and infrastructure layers used across the application.
+
+## Key Files
+
+### Validation Layer (`validations.ts`)
+
+**Purpose**: Input validation and type safety using Zod schemas
+
+- `ProjectInputSchema`: Project data validation (1-10 tags, 1-10 links)
+- `WebhookPayloadSchema`: Webhook request validation with API key auth
+- `KeywordInputSchema`: Keyword cloud data with visual config
+- `ProjectQuerySchema`: Query parameter validation (search, tags, status, pagination)
+- `ExternalLinkSchema`: URL validation with http/https protocol check
+- `TaskStatusEnum`: Discovery task states (PENDING/IN_PROGRESS/COMPLETED/FAILED)
+
+### Prisma Client (`prisma.ts`)
+
+**Purpose**: Singleton database client pattern
+
+```typescript
+import { prisma } from "@/lib/prisma";
+```
+
+### Utilities
+
+- `utils.ts`: `cn()` - Tailwind class merging with clsx/twMerge
+- `slug.ts`: `generateSlug()` - URL-friendly slug generation (prefers English, max 100 chars)
+
+### GitHub Integration
+
+- `github/api.ts`: `getGitHubStats()` - Fetch repo stats (stars, forks, license) with 5min cache
+- `github/badges.ts`: `parseGitHubUrl()`, `getGitHubStarsBadgeUrl()`, `getAllGitHubBadgeUrls()`
+
+## Usage Patterns
+
+**Validation**:
+
+```typescript
+import { ProjectInputSchema } from "@/lib/validations";
+const validated = ProjectInputSchema.parse(inputData);
+```
+
+**Database**:
+
+```typescript
+import { prisma } from "@/lib/prisma";
+const projects = await prisma.project.findMany();
+```
+
+**GitHub Badges**:
+
+```typescript
+import { getGitHubBadgesFromLinks } from "@/lib/github/badges";
+const { stars } = getGitHubBadgesFromLinks(project.externalLinks);
+```
+
+## Key Design Decisions
+
+- Singleton Prisma client prevents connection pool exhaustion in dev
+- All enums use Zod for runtime type checking
+- API key minimum length: 32 characters
+- URL validation enforces http/https protocol only