map-project

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

<EXTREMELY-IMPORTANT> If you are about to update CLAUDE.md, you **ABSOLUTELY MUST** complete Phase 0 (detection) and Phase 1 (discovery) first.

SKIPPING DISCOVERY = INCOMPLETE DOCUMENTATION = AI AGENT FAILURE

This is not optional. You cannot rationalize "good enough" without running verification checks. </EXTREMELY-IMPORTANT>

<EXTREMELY-IMPORTANT> 如果您要更新CLAUDE.md，**必须**先完成第0阶段（检测）和第1阶段（探索）。

跳过探索阶段=文档不完整=AI AGENT执行失败

这不是可选步骤。不进行验证检查，您不能自我合理化“已经足够好”。 </EXTREMELY-IMPORTANT>

Update CLAUDE.md After Installation

安装后更新CLAUDE.md

MANDATORY FIRST RESPONSE PROTOCOL

强制首响应协议

Before writing ANY documentation:

☐ Complete Phase 0: Detect the framework
☐ Complete Phase 1: Framework-specific discovery (ALL steps)
☐ Create API surface inventory with counts
☐ Verify >90% coverage is achievable
☐ Announce: "Detected [Framework]. Starting documentation update targeting 10/10"

Writing docs without discovery = guaranteed gaps. Phase 0 + Phase 1 are NON-NEGOTIABLE.

在编写任何文档之前：

☐ 完成第0阶段：检测框架
☐ 完成第1阶段：框架专属探索（所有步骤）
☐ 创建带统计数的API表面清单
☐ 验证可实现>90%的覆盖率
☐ 发布通知：“检测到[Framework]。开始更新文档，目标达成10/10质量评分”

未进行探索就编写文档=必然存在遗漏。第0+1阶段是不可协商的强制步骤。

Overview

概述

After installing framework agents, CLAUDE.md and its imported files contain generic placeholder examples. This skill guides you to systematically discover the actual project patterns and update these files with real, project-specific information.

Core principle: Discover exhaustively, then document. Analyze ALL exports/classes/routes before writing.

Quality target: 10/10 AI agent effectiveness — documentation should enable an AI to implement features correctly on the first attempt.

Supported frameworks: Laravel, Next.js (App Router), NestJS, Expo/React Native (expo-router), Node.js monorepo.

安装框架Agent后，CLAUDE.md及其导入文件包含通用占位符示例。本技能将指导您系统性地探索实际项目模式，并用真实的、项目专属的信息更新这些文件。

核心原则：先全面探索，再编写文档。在编写前分析所有导出项/类/路由。

质量目标：AI Agent效能达到10/10 —— 文档应能让AI首次尝试就正确实现功能。

支持的框架： Laravel、Next.js（App Router）、NestJS、Expo/React Native（expo-router）、Node.js monorepo。

Context Budget Limits

上下文预算限制

Your documentation MUST fit within these constraints:

Component	Max Lines	Rationale
Main CLAUDE.md	1,000	Always loaded, keep lean
Each @import file	500	Lazy-loaded, can be detailed
All imports combined	1,500	~3k tokens = 1.5% of context
Total	2,500	Leaves 98%+ for actual work

您的文档必须符合以下约束：

组件	最大行数	理由
主文件CLAUDE.md	1,000	始终加载，需保持精简
每个@import文件	500	懒加载，可更详细
所有导入文件总计	1,500	~3k tokens = 占上下文的1.5%
总计	2,500	为实际工作保留98%+的上下文空间

If Over Budget

超出预算时的处理

Move code examples >30 lines to "reference by path" format
Convert prose to tables (3x more token-efficient)
Consolidate overlapping sections
Remove redundant information between files

将超过30行的代码示例转为“按路径引用”格式
将散文式内容转为表格（token效率提升3倍）
合并重叠章节
移除文件间的冗余信息

What Makes 10/10 Documentation

何为10/10质量的文档

AI agents are most effective when documentation provides:

当文档提供以下内容时，AI Agent的效能最高：

1. Step-by-Step Implementation Guides

1. 分步实现指南

❌ Poor (4/10): "We use controllers for API endpoints" ✅ Excellent (10/10): Numbered steps with actual code templates from the codebase

markdown

undefined

❌ 劣质（4/10）：“我们使用控制器处理API端点” ✅ 优秀（10/10）：带代码库中真实代码模板的编号步骤

markdown

undefined

Adding a New API Endpoint (Laravel)

添加新API端点（Laravel）

Step 1: Create the Model

步骤1：创建模型

php

class ModelName extends Model
{
    use BelongsToAccount, HasUuids;
    protected $fillable = ['account_id', 'name'];
}

php

class ModelName extends Model
{
    use BelongsToAccount, HasUuids;
    protected $fillable = ['account_id', 'name'];
}

Step 2: Create the Form Request

步骤2：创建表单请求

Step 3: Create the Controller (thin — delegates to Service)

步骤3：创建控制器（轻量型 —— 委托给Service）

Step 4: Register Routes in routes/api.php

步骤4：在routes/api.php中注册路由

undefined

undefined

2. Response Formats

2. 响应格式

❌ Poor: "API returns JSON" ✅ Excellent: Every response shape with types

markdown

// NestJS — Interceptor wraps all responses:
{ success: true, data: T, timestamp: string }

// Error — Exception Filter formats:
{ success: false, error: string, code: 'ERROR_CODE', details: [...] }

❌ 劣质：“API返回JSON” ✅ 优秀：带类型的完整响应结构

markdown

// NestJS —— 拦截器包装所有响应:
{ success: true, data: T, timestamp: string }

// 错误 —— 异常过滤器格式化:
{ success: false, error: string, code: 'ERROR_CODE', details: [...] }

3. State Machines with Visual Diagrams

3. 状态机与可视化图表

markdown

undefined

markdown

undefined

Gift Redemption State Machine

礼品兑换状态机

pending → fulfilled
    ↓
cancelled

Current	Action	New State	Who
pending	Admin approves	fulfilled	Admin
pending	Admin cancels	cancelled	Admin

undefined

pending → fulfilled
    ↓
cancelled

当前状态	操作	新状态	执行者
pending	管理员批准	fulfilled	管理员
pending	管理员取消	cancelled	管理员

undefined

4. Route/Screen Tables

4. 路由/页面表格

❌ Poor: "Routes are in the routes folder" ✅ Excellent: Complete table with all routes

markdown

| Route | File | Type | Purpose |
|-------|------|------|---------|
| `/` | app/page.tsx | Server Component | Home page |
| `/dashboard/[id]` | app/dashboard/[id]/page.tsx | Server Component | User detail |
| `/api/users` | app/api/users/route.ts | GET, POST | User CRUD |

❌ 劣质：“路由存放在routes文件夹中” ✅ 优秀：包含所有路由的完整表格

markdown

| 路由 | 文件 | 类型 | 用途 |
|-------|------|------|---------|
| `/` | app/page.tsx | Server Component | 首页 |
| `/dashboard/[id]` | app/dashboard/[id]/page.tsx | Server Component | 用户详情页 |
| `/api/users` | app/api/users/route.ts | GET, POST | 用户CRUD |

5. API Surface Tables

5. API表面表格

markdown

| Export | Type | Purpose |
|--------|------|---------|
| parseMarkdownToBlocks | function | Parse plan text → Block[] |
| Plan | interface | Full plan with versions |

markdown

| 导出项 | 类型 | 用途 |
|--------|------|---------|
| parseMarkdownToBlocks | 函数 | 解析纯文本 → Block[] |
| Plan | 接口 | 带版本的完整计划 |

When to Use

使用场景

Initial install: User just installed agents and CLAUDE.md has generic examples
Project start: Beginning work on a project for the first time
Key milestones: After major architecture changes
Periodic refresh: User asks to "update docs" or "sync CLAUDE.md with project"

初始安装后：用户刚安装Agent，CLAUDE.md中只有通用示例
项目启动时：首次开始处理某个项目
关键里程碑后：重大架构变更完成后
定期刷新：用户要求“更新文档”或“同步CLAUDE.md与项目”

Common Rationalizations (All Wrong)

常见错误合理化借口（全错）

"I already know this codebase" → STILL do Phase 1 discovery
"The exports haven't changed much" → STILL verify counts
"This is a small project" → STILL create all 3 required files
"80% coverage is good enough" → NO, 90% minimum
"I can eyeball the exports" → Use search commands, not memory
"Wrong framework won't matter" → Phase 0 detection is MANDATORY

“我已经熟悉这个代码库了” → 仍需执行第1阶段探索
“导出项没什么变化” → 仍需验证统计数
“这是个小项目” → 仍需创建所有3个必填文件
“80%的覆盖率足够了” → 不行，最低要求90%
“我可以目测导出项” → 使用搜索命令，而非依赖记忆
“框架识别错误没关系” → 第0阶段检测是强制步骤

Phase 0: Framework Detection (MANDATORY)

第0阶段：框架检测（强制）

Before discovery, detect the framework. Check in this order (most specific first):


app/Models/
app/page.tsx
src/**/*.module.ts
app/_layout.tsx
packages/*/src/index.ts

#	Check	Confirming Files	Framework
1	`composer.json` + `artisan`	`app/Models/` , `routes/api.php`	Laravel
2	`next.config.*` exists	`app/page.tsx` or `src/app/page.tsx`	Next.js
3	`nest-cli.json` OR `@nestjs/core` in package.json	`src/*/.module.ts`	NestJS
4	`app.json` with `"expo"` key	`app/_layout.tsx` (expo-router)	Expo/React Native
5	`package.json` + `packages/*/package.json`	`packages/*/src/index.ts`	Node.js monorepo

Announce: "Detected [Framework]. Proceeding with framework-specific discovery."

If multiple match (e.g. monorepo containing Next.js app): use the most specific framework for the primary app. Document sub-packages separately if needed.

探索前，先检测框架。按以下顺序检查（从最具特异性的开始）：


app/Models/
app/page.tsx
src/**/*.module.ts
app/_layout.tsx
packages/*/src/index.ts

序号	检查项	确认文件	框架
1	`composer.json` + `artisan`	`app/Models/` , `routes/api.php`	Laravel
2	存在 `next.config.*`	`app/page.tsx` 或 `src/app/page.tsx`	Next.js
3	存在 `nest-cli.json` 或 package.json中有 `@nestjs/core`	`src/*/.module.ts`	NestJS
4	`app.json` 包含 `"expo"` 键	`app/_layout.tsx` （expo-router）	Expo/React Native
5	`package.json` + `packages/*/package.json`	`packages/*/src/index.ts`	Node.js monorepo

发布通知： “检测到**[Framework]**。开始执行框架专属探索。”

如果多个框架匹配（例如包含Next.js应用的monorepo）：为主应用使用最具特异性的框架。如有需要，单独记录子包。

Phase 1: Exhaustive Discovery (MANDATORY)

第1阶段：全面探索（强制）

Do NOT skip this phase. Follow the steps for your detected framework.

请勿跳过此阶段。 按照检测到的框架执行步骤。

Laravel

Models:
```
ls app/Models/*.php
```
— list all, note relationships (
```
belongsTo
```
,
```
hasMany
```
,
```
belongsToMany
```
), scopes, casts
Services:
```
ls app/Services/**/*.php
```
— list key public methods per service
Jobs:
```
ls app/Jobs/*.php
```
— note what dispatches each (Observer, Command, other Job)
Observers:
```
ls app/Observers/*.php
```
— which model, which events (
```
created
```
,
```
updated
```
)

Middleware:

ls app/Http/Middleware/*.php

— note alias from

bootstrap/app.php

API Resources:
```
ls app/Http/Resources/*.php
```
— which model each transforms
Form Requests:
```
ls app/Http/Requests/*.php
```
— key validation rules per request
Routes:
```
grep "Route::" routes/api.php
```
— extract ALL methods, paths, controllers, middleware groups

Commands:

ls app/Console/Commands/*.php

+ schedules from

routes/console.php

Also scan:

app/Enums/

app/Traits/

app/Contracts/

app/Mail/

模型：
```
ls app/Models/*.php
```
—— 列出所有模型，记录关联关系（
```
belongsTo
```
,
```
hasMany
```
,
```
belongsToMany
```
）、作用域、类型转换
服务：
```
ls app/Services/**/*.php
```
—— 记录每个服务的关键公共方法
任务：
```
ls app/Jobs/*.php
```
—— 记录每个任务的触发者（Observer、Command、其他Job）
观察者：
```
ls app/Observers/*.php
```
—— 记录对应的模型和监听事件（
```
created
```
,
```
updated
```
）

中间件：

ls app/Http/Middleware/*.php

—— 记录

bootstrap/app.php

中的别名

API资源：
```
ls app/Http/Resources/*.php
```
—— 记录每个资源转换的模型
表单请求：
```
ls app/Http/Requests/*.php
```
—— 记录每个请求的关键验证规则
路由：
```
grep "Route::" routes/api.php
```
—— 提取所有方法、路径、控制器、中间件组

命令：

ls app/Console/Commands/*.php

routes/console.php

中的调度任务

额外扫描：

app/Enums/

app/Traits/

app/Contracts/

app/Mail/

Next.js (App Router)

Next.js（App Router）

Page routes:

find app -name 'page.tsx' -o -name 'page.ts'

(or

src/app/

) — derive URL from path

API routes:

find app/api -name 'route.ts'

— grep for exported

GET

POST

PUT

DELETE

PATCH

Layouts:
```
find app -name 'layout.tsx'
```
— note which routes each wraps

Server Actions:

grep -r "'use server'" src --include="*.ts" --include="*.tsx"

— list all action functions

Client Components:
```
grep -rl "'use client'" src
```
— identify interactive components

Middleware:

find . -maxdepth 2 -name 'middleware.ts'

— note matcher config

Hooks:

find src/hooks -name '*.ts' -o -name '*.tsx'

— list custom hooks

Types:

grep -rh "^export interface\|^export type" src/types --include="*.ts"

页面路由：

find app -name 'page.tsx' -o -name 'page.ts'

（或

src/app/

）—— 从路径推导URL

API路由：

find app/api -name 'route.ts'

—— 搜索导出的

GET

POST

PUT

DELETE

PATCH

布局：
```
find app -name 'layout.tsx'
```
—— 记录每个布局包裹的路由

Server Actions：

grep -r "'use server'" src --include="*.ts" --include="*.tsx"

—— 列出所有动作函数

客户端组件：
```
grep -rl "'use client'" src
```
—— 识别交互式组件

中间件：

find . -maxdepth 2 -name 'middleware.ts'

—— 记录匹配器配置

钩子：

find src/hooks -name '*.ts' -o -name '*.tsx'

—— 列出自定义钩子

类型：

grep -rh "^export interface\|^export type" src/types --include="*.ts"

NestJS

Modules:
```
find src -name '*.module.ts'
```
— note imports, exports, controllers, providers per module

Controllers:

find src -name '*.controller.ts'

— grep

@Controller

@Get

@Post

@Put

@Delete

@Patch

Services:
```
find src -name '*.service.ts'
```
— list key methods

Entities:

find src -path '*/entities/*.ts' -o -path '*/entity/*.ts'

— note properties, relationships

DTOs:

find src -path '*/dtos/*.ts' -o -path '*/dto/*.ts'

— note class-validator decorators

Guards:
```
find src -name '*.guard.ts'
```
— what they protect (JWT, roles, etc.)
Pipes:
```
find src -name '*.pipe.ts'
```
— validation/transformation purpose
Interceptors:
```
find src -name '*.interceptor.ts'
```
— logging, response transform, caching
Filters:
```
find src -name '*.filter.ts'
```
— exception handling
Decorators:
```
find src/common/decorators -name '*.ts'
```
— custom metadata annotations

模块：
```
find src -name '*.module.ts'
```
—— 记录每个模块的导入、导出、控制器、提供者

控制器：

find src -name '*.controller.ts'

—— 搜索

@Controller

@Get

@Post

@Put

@Delete

@Patch

服务：
```
find src -name '*.service.ts'
```
—— 列出关键方法

实体：

find src -path '*/entities/*.ts' -o -path '*/entity/*.ts'

—— 记录属性、关联关系

DTO：

find src -path '*/dtos/*.ts' -o -path '*/dto/*.ts'

—— 记录class-validator装饰器

守卫：
```
find src -name '*.guard.ts'
```
—— 记录保护对象（JWT、角色等）
管道：
```
find src -name '*.pipe.ts'
```
—— 记录验证/转换用途
拦截器：
```
find src -name '*.interceptor.ts'
```
—— 记录日志、响应转换、缓存功能
过滤器：
```
find src -name '*.filter.ts'
```
—— 记录异常处理逻辑
装饰器：
```
find src/common/decorators -name '*.ts'
```
—— 记录自定义元数据注解

Expo/React Native (expo-router)

Expo/React Native（expo-router）

Screen routes:

find app -name '*.tsx' ! -name '_layout.tsx' ! -name '+not-found.tsx'

— derive URL from path

Layouts:
```
find app -name '_layout.tsx'
```
— navigation type (Stack, Tabs, Drawer)
Components:
```
find src/components -name '*.tsx'
```
— categorize: ui, shared, features

Hooks:

find src -name 'use*.ts' -o -name 'use*.tsx'

— global + module-specific

Stores:

find src -name '*Store.ts' -o -name '*store.ts'

— Zustand/Redux state + actions

API hooks:

grep -rl "useQuery\|useMutation" src --include="*.ts"

— React Query hooks

Services:
```
find src/services -name '*.ts'
```
— API client, storage, notifications

Types:

grep -rh "^export interface\|^export type" src --include="*.ts" | sort | uniq

Platform-specific:

find . -name '*.ios.tsx' -o -name '*.android.tsx' -o -name '*.web.tsx'

页面路由：

find app -name '*.tsx' ! -name '_layout.tsx' ! -name '+not-found.tsx'

—— 从路径推导URL

布局：
```
find app -name '_layout.tsx'
```
—— 记录导航类型（Stack、Tabs、Drawer）
组件：
```
find src/components -name '*.tsx'
```
—— 分类：ui、shared、features

钩子：

find src -name 'use*.ts' -o -name 'use*.tsx'

—— 全局+模块专属钩子

状态存储：
```
find src -name '*Store.ts' -o -name '*store.ts'
```
—— Zustand/Redux状态+动作

API钩子：

grep -rl "useQuery\|useMutation" src --include="*.ts"

—— React Query钩子

服务：
```
find src/services -name '*.ts'
```
—— API客户端、存储、通知

类型：

grep -rh "^export interface\|^export type" src --include="*.ts" | sort | uniq

平台专属文件：

find . -name '*.ios.tsx' -o -name '*.android.tsx' -o -name '*.web.tsx'

Node.js Monorepo

Packages:

ls packages/*/package.json

— find entry points via

jq '.main, .exports'

Exports:
```
grep "^export" packages/*/src/index.ts
```
— count types, functions, constants

Subpath exports:

find packages/*/src -name "index.ts"

+ check

"exports"

in package.json

TypeScript interfaces:

grep -rh "^export interface\|^export type" packages/*/src --include="*.ts"

Route handlers:

grep -r "router\.\|app\.\(get\|post\|put\|delete\)" --include="*.ts"

State machines: Look for entities with
```
status
```
or
```
state
```
fields

包：

ls packages/*/package.json

—— 通过

jq '.main, .exports'

找到入口点

导出项：
```
grep "^export" packages/*/src/index.ts
```
—— 统计类型、函数、常量的数量

子路径导出：

find packages/*/src -name "index.ts"

+ 检查package.json中的

"exports"

TypeScript接口：

grep -rh "^export interface\|^export type" packages/*/src --include="*.ts"

路由处理器：

grep -r "router\.\|app\.\(get\|post\|put\|delete\)" --include="*.ts"

状态机：查找包含
```
status
```
或
```
state
```
字段的实体

Inventory Checklist (all frameworks)

清单检查（所有框架）

Before proceeding to Phase 2, you MUST have:

Complete list of all discoverable items with counts
All routes/screens mapped
All state machines identified (entities with status/state fields)
Import/use patterns noted

进入第2阶段前，您必须完成：

所有可探索项的完整列表及统计数
所有路由/页面已映射
所有状态机已识别（含status/state字段的实体）
记录了导入/使用模式

Phase 2: Required Output Files

第2阶段：必填输出文件

You MUST create/update these 3 files. No exceptions.

您必须创建/更新以下3个文件，无例外。

File 1:

exports-reference.md

(REQUIRED)

文件1：

exports-reference.md

（必填）

Location:

.claude/claude-md-refs/exports-reference.md

Target: 300-500 lines | Coverage: >90% of discovered items

Use framework-appropriate sections:

位置：

.claude/claude-md-refs/exports-reference.md

目标行数： 300-500行 | 覆盖率： >90%的已探索项

使用框架专属的章节：

Laravel

Section	Table Columns
Models	Model, Table, Key Relationships, Scopes
Enums	Enum, Cases, Backing Type
Services	Service, Key Methods, Purpose
Contracts	Interface, Methods, Implementations
Jobs	Job, Dispatched By, Purpose
Console Commands	Command, Signature, Schedule
Middleware	Alias, Class, Purpose
Observers	Observer, Model, Triggers
API Resources	Resource, Model, Purpose
Form Requests	Request, Controller, Key Validation Rules
Mailables	Mailable, View, Purpose
Traits	Trait, Used By, Purpose

End with Import Patterns:

use App\Models\Toast;

use App\Services\ToastService;

章节	表格列
模型	模型名、表名、关键关联关系、作用域
枚举	枚举名、枚举值、底层类型
服务	服务名、关键方法、用途
契约	接口名、方法、实现类
任务	任务名、触发者、用途
控制台命令	命令名、签名、调度规则
中间件	别名、类名、用途
观察者	观察者名、模型、触发事件
API资源	资源名、模型、用途
表单请求	请求名、控制器、关键验证规则
邮件类	邮件类名、视图、用途
Trait	Trait名、使用者、用途

结尾添加导入模式：

use App\Models\Toast;

use App\Services\ToastService;

Next.js

Section	Table Columns
Page Routes	Route, File, Type (Server/Client), Purpose
API Routes	Route, Method, File, Purpose
Server Actions	Action, File, Parameters, Return
Middleware	Middleware, File, Purpose
Layouts	Layout, File, Scope
Custom Hooks	Hook, File, Purpose
Types	Type, File, Purpose

章节	表格列
页面路由	路由、文件、类型（Server/Client）、用途
API路由	路由、方法、文件、用途
Server Actions	动作名、文件、参数、返回值
中间件	中间件名、文件、用途
布局	布局名、文件、作用范围
自定义钩子	钩子名、文件、用途
类型	类型名、文件、用途

NestJS

Section	Table Columns
Modules	Module, Exports, Purpose
Controllers & Routes	Controller, Method, Route, Guards, Pipes
Services	Service, Methods, Purpose
Entities	Entity, Properties, Relationships
DTOs	DTO, Fields, Validators
Guards	Guard, Purpose, Scope
Pipes	Pipe, Purpose, Applied
Interceptors	Interceptor, Purpose, Scope
Filters	Filter, Exception Type, Purpose
Decorators	Decorator, Purpose, Usage

章节	表格列
模块	模块名、导出项、用途
控制器与路由	控制器、方法、路由、守卫、管道
服务	服务名、方法、用途
实体	实体名、属性、关联关系
DTO	DTO名、字段、验证器
守卫	守卫名、用途、作用范围
管道	管道名、用途、应用场景
拦截器	拦截器名、用途、作用范围
过滤器	过滤器名、异常类型、用途
装饰器	装饰器名、用途、用法

Expo/React Native

Section	Table Columns
Routes/Screens	Route, File, Dynamic Params, Layout, Purpose
Components	Component, Path, Category (ui/shared/feature), Purpose
Hooks	Hook, Path, Parameters, Returns, Purpose
Services	Service, Path, Key Methods, Purpose
Stores	Store, Path, State, Actions, Purpose
API Hooks	Hook, Path, Type (Query/Mutation), Cache Key, Purpose
Types	Type, Path, Key Fields, Purpose
Constants	Constant, Path, Value/Type, Purpose
Platform-Specific	Component, Platforms, Files, Purpose

章节	表格列
路由/页面	路由、文件、动态参数、布局、用途
组件	组件名、路径、分类（ui/shared/feature）、用途
钩子	钩子名、路径、参数、返回值、用途
服务	服务名、路径、关键方法、用途
状态存储	存储名、路径、状态、动作、用途
API钩子	钩子名、路径、类型（Query/Mutation）、缓存键、用途
类型	类型名、路径、关键字段、用途
常量	常量名、路径、值/类型、用途
平台专属	组件名、平台、文件、用途

Node.js Monorepo

Section	Table Columns
@scope/package Types	Export, Type, Purpose
@scope/package Functions	Export, Purpose, Returns
@scope/package Constants	Export, Value, Purpose
Subpath Exports	Subpath, Export, Purpose

End with Import Patterns:

import { Type } from '@scope/package';

章节	表格列
@scope/package 类型	导出项、类型、用途
@scope/package 函数	导出项、用途、返回值
@scope/package 常量	导出项、值、用途
子路径导出	子路径、导出项、用途

结尾添加导入模式：

import { Type } from '@scope/package';

File 2:

development-guide.md

(REQUIRED)

文件2：

development-guide.md

（必填）

Location:

.claude/claude-md-refs/development-guide.md

Target: 300-500 lines

Must include framework-appropriate implementation guides:

Framework	Required Guides
Laravel	Adding a New API Endpoint (7 steps: Model → Migration → Form Request → Resource → Service → Controller → Routes), Response Format ( `ApiResponse` ), Adding Notifications (Observer → Job), Adding Commands, Multi-tenancy pattern, Testing
Next.js	Adding a Page Route, Adding an API Route, Adding a Server Action, Adding Middleware, Data Fetching (Server vs Client), Response Format, Testing
NestJS	Adding a Feature Module (8 steps: Module → Entity → DTO → Repository → Service → Controller → Register → Import), Creating Guards/Pipes/Interceptors, Response Format, Testing
Expo/RN	Adding a Screen/Route (create in `app/` , implement, configure `_layout.tsx` ), Adding API Calls (React Query: types → hook → component), Adding Navigation (Tab/Stack/Drawer), Adding State (Zustand + AsyncStorage), Testing, Environment Variables, Building (EAS)
Node.js	Adding a Route Handler, Adding an Integration, Response Format, Error Handling, Testing

All guides must use actual code from the codebase, not placeholders.

位置：

.claude/claude-md-refs/development-guide.md

目标行数： 300-500行

必须包含框架专属的实现指南：

框架	必填指南
Laravel	添加新API端点（7步：模型→迁移→表单请求→资源→服务→控制器→路由）、响应格式（ `ApiResponse` ）、添加通知（观察者→任务）、添加命令、多租户模式、测试
Next.js	添加页面路由、添加API路由、添加Server Action、添加中间件、数据获取（Server vs Client）、响应格式、测试
NestJS	添加功能模块（8步：模块→实体→DTO→仓库→服务→控制器→注册→导入）、创建守卫/管道/拦截器、响应格式、测试
Expo/RN	添加页面/路由（在 `app/` 中创建、实现、配置 `_layout.tsx` ）、添加API调用（React Query：类型→钩子→组件）、添加导航（Tab/Stack/Drawer）、添加状态管理（Zustand + AsyncStorage）、测试、环境变量、构建（EAS）
Node.js	添加路由处理器、添加集成、响应格式、错误处理、测试

所有指南必须使用代码库中的真实代码，而非占位符。

File 3:

architecture.md

(REQUIRED)

文件3：

architecture.md

（必填）

Location:

.claude/claude-md-refs/architecture.md

Target: 300-500 lines

All frameworks need these core sections:

Dependency/Import Graph — ASCII diagram showing how components depend on each other
Request/Data Lifecycle — Flow from entry to response
Routes/Screens Table — ALL routes with methods, handlers/files, auth requirements
State Machines — ASCII diagram + transition table for each stateful entity
Key Subsystems — 1 paragraph + key files per major subsystem

Framework-specific additions:

Framework	Extra Sections
Laravel	Multi-tenancy tree (Account → scoped models), Observer → Job async flow, Docker services, Scheduled commands
Next.js	Server/Client Component boundary, Caching strategy (ISR, revalidate), RSC payload flow
NestJS	DI/IoC container flow, Module import/export graph, Request pipeline (Middleware → Guards → Interceptors → Pipes → Handler → Interceptors → Filters)
Expo/RN	Navigation tree (Stack/Tab/Drawer nesting), Data flow layers (Screen → Hook → API Hook → Service → Backend), State management strategy table, Offline strategy, Authentication flow, Deep linking
Node.js	Package dependency graph, Subpath export map

位置：

.claude/claude-md-refs/architecture.md

目标行数： 300-500行

所有框架都需要以下核心章节：

依赖/导入图 —— ASCII图表展示组件间的依赖关系
请求/数据生命周期 —— 从入口到响应的流程
路由/页面表格 —— 所有路由，含方法、处理器/文件、认证要求
状态机 —— 每个有状态实体的ASCII图表+转换表
关键子系统 —— 每个主要子系统1段描述+关键文件

框架专属扩展章节：

框架	额外章节
Laravel	多租户树（Account→作用域模型）、观察者→任务异步流程、Docker服务、调度命令
Next.js	Server/Client组件边界、缓存策略（ISR、重验证）、RSC payload流程
NestJS	DI/IoC容器流程、模块导入/导出图、请求管道（中间件→守卫→拦截器→管道→处理器→拦截器→过滤器）
Expo/RN	导航树（Stack/Tab/Drawer嵌套）、数据流层（页面→钩子→API钩子→服务→后端）、状态管理策略表、离线策略、认证流程、深度链接
Node.js	包依赖图、子路径导出映射

File 4: Update

CLAUDE.md

文件4：更新

CLAUDE.md

Add imports and Quick Reference table:

markdown

undefined

添加导入和快速参考表格：

markdown

undefined

Project Documentation

项目文档

@.claude/claude-md-refs/architecture.md @.claude/claude-md-refs/development-guide.md @.claude/claude-md-refs/exports-reference.md

Quick Documentation Reference

快速文档参考

Need Help With	See File
Adding features, endpoints, screens	development-guide.md
Understanding system structure, flows	architecture.md
Finding models, services, hooks, exports	exports-reference.md

---

需要帮助的场景	查看文件
添加功能、端点、页面	development-guide.md
理解系统结构、流程	architecture.md
查找模型、服务、钩子、导出项	exports-reference.md

---

Phase 3: Verification (MANDATORY)

第3阶段：验证（强制）

Do NOT mark complete until ALL checks pass.

所有检查通过前，请勿标记任务完成。

Check 1: API Surface Coverage (>90%)

检查1：API表面覆盖率（>90%）

Run framework-appropriate count:

Framework	Actual Count Command	Documented Count
Laravel	`find app -name "*.php" -type f \| wc -l`	`grep -c "^\|" .claude/claude-md-refs/exports-reference.md`
Next.js	`find app -name 'page.tsx' -o -name 'route.ts' \| wc -l`	Count route table rows
NestJS	`find src -name '.module.ts' -o -name '.controller.ts' -o -name '*.service.ts' \| wc -l`	Count module/controller/service rows
Expo/RN	`find app -name '.tsx' ! -name '_layout.tsx' \| wc -l` + `find src -name 'use.ts' \| wc -l`	Count route + hook rows
Node.js	`grep -rh "^export" packages/*/src/index.ts \| wc -l`	Count export table rows

FAIL if: Coverage < 90%. Go back to Phase 1.

执行框架专属的统计命令：

框架	实际数量统计命令	文档记录数量统计方式
Laravel	`find app -name "*.php" -type f \| wc -l`	`grep -c "^\|" .claude/claude-md-refs/exports-reference.md`
Next.js	`find app -name 'page.tsx' -o -name 'route.ts' \| wc -l`	统计路由表格行数
NestJS	`find src -name '.module.ts' -o -name '.controller.ts' -o -name '*.service.ts' \| wc -l`	统计模块/控制器/服务表格行数
Expo/RN	`find app -name '.tsx' ! -name '_layout.tsx' \| wc -l` + `find src -name 'use.ts' \| wc -l`	统计路由+钩子表格行数
Node.js	`grep -rh "^export" packages/*/src/index.ts \| wc -l`	统计导出项表格行数

不通过条件： 覆盖率<90%。返回第1阶段重新执行。

Check 2: Context Budget

检查2：上下文预算

bash

wc -l CLAUDE.md .claude/claude-md-refs/*.md

FAIL if: CLAUDE.md > 1,000 lines, any import > 500, total > 2,500.

bash

wc -l CLAUDE.md .claude/claude-md-refs/*.md

不通过条件： CLAUDE.md>1000行，任何导入文件>500行，总计>2500行。

Check 3: Required Sections

检查3：必填章节完整性

exports-reference.md: Has table for EACH category, has Import/Use Patterns section development-guide.md: Has "Adding a New X" with numbered steps and actual code architecture.md: Has dependency graph, request lifecycle, route/screen table, state machines (if any)

exports-reference.md： 每个分类都有表格，包含导入/使用模式章节 development-guide.md： 包含“添加新X”的带真实代码的分步指南 architecture.md： 包含依赖图、请求生命周期、路由/页面表格、状态机（如有）

Check 4: No Duplicates

检查4：无重复内容

No information duplicated between CLAUDE.md and import files, or between import files.

CLAUDE.md与导入文件之间、导入文件之间无重复信息。

Check 5: AI Effectiveness Test

检查5：AI效能测试

Can an AI agent now:

Find any model/service/hook/export by searching exports-reference.md?
Add a new feature by following development-guide.md step-by-step?
Understand the system architecture from architecture.md?
Know which file to read for any task from CLAUDE.md Quick Reference?

If ANY answer is "no", the documentation is incomplete.

现在AI Agent能否：

通过搜索exports-reference.md找到任意模型/服务/钩子/导出项？
按照development-guide.md的分步指南添加新功能？
从architecture.md理解系统架构？
通过CLAUDE.md的快速参考知道该查看哪个文件？

如果任何一个答案是“否”，则文档不完整。

Quality Checklist (Must Score 10/10)

质量检查表（需达到10/10）

Category	0 points	1 point	2 points
API Surface Coverage	<50% documented	50-89%	>90% in tables
Implementation Guidance	Describes what exists	Shows file locations	Step-by-step with code templates
State/Workflow Diagrams	No diagrams	Lists states	ASCII diagram + transition table
Routes/Screens	No route docs	Lists some routes	Complete table with methods, auth
Context Efficiency	Over budget	Within budget, has duplication	Within budget, no duplication

Total: 10/10 required to complete this skill.

分类	0分	1分	2分
API表面覆盖率	<50%已记录	50-89%	>90%已记录在表格中
实现指导	仅描述现有内容	展示文件位置	带代码模板的分步指南
状态/工作流图表	无图表	仅列出状态	ASCII图表+转换表
路由/页面	无路由文档	仅列出部分路由	包含方法、认证信息的完整表格
上下文效率	超出预算	在预算内但有重复	在预算内且无重复

总分：需达到10/10才能完成本技能。

Common Mistakes

常见错误

Mistake	Fix
Skipping framework detection	Phase 0 prevents using wrong discovery commands
Using Node.js patterns for Laravel	PHP has classes/traits/models, not exports/packages
Using controller patterns for Next.js	Next.js uses file-based routing, not controller classes
Generic descriptions	Every code example must come from the actual codebase
Missing exports-reference.md	This file is REQUIRED, not optional
Over context budget	Tables > prose, reference by path for code >30 lines
Self-assessing "good enough"	Use objective verification checks

错误	修复方案
跳过框架检测	第0阶段可避免使用错误的探索命令
对Laravel项目使用Node.js模式	PHP使用类/trait/模型，而非导出项/包
对Next.js项目使用控制器模式	Next.js使用基于文件的路由，而非控制器类
通用描述	所有代码示例必须来自实际代码库
缺少exports-reference.md	该文件是必填项，不可选
超出上下文预算	优先使用表格而非散文，对超过30行的代码采用按路径引用
自我评估“已经足够好”	使用客观的验证检查

Failure Modes

失败模式

Failure Mode 1: Skipping Discovery

失败模式1：跳过探索阶段

Symptom: Writing docs immediately, missing 40%+ of items Fix: Phase 1 is MANDATORY. Complete inventory before writing ANY documentation.

症状： 立即编写文档，遗漏40%+的内容 修复： 第1阶段是强制步骤。编写任何文档前必须完成清单整理。

Failure Mode 2: Wrong Framework Detection

失败模式2：框架识别错误

Symptom: Using

grep "^export"

on a Laravel project, or scanning

app/Models/

on a Next.js project Fix: Phase 0 detection is MANDATORY. Check files in priority order.

症状： 对Laravel项目执行

grep "^export"

，或对Next.js项目扫描

app/Models/

修复： 第0阶段检测是强制步骤，按优先级顺序检查文件。

Failure Mode 3: Generic Templates

失败模式3：使用通用模板

Symptom: Copy-pasting skill templates without actual project code Fix: Every code example must come from the actual codebase. No placeholders.

症状： 直接复制技能模板，未替换为实际项目代码 修复： 所有代码示例必须来自实际代码库，禁止使用占位符。

Failure Mode 4: Over Budget

失败模式4：超出预算

Symptom: CLAUDE.md > 1000 lines, context bloat Fix: Tables > prose, reference by path for code >30 lines, consolidate sections.

症状： CLAUDE.md>1000行，上下文膨胀 修复： 优先使用表格而非散文，对超过30行的代码采用按路径引用，合并章节。

Failure Mode 5: Self-Assessing "Good Enough"

失败模式5：自我评估“足够好”

Symptom: Marking complete at 70% coverage without running verification commands Fix: Run ALL verification checks. Must pass ALL 5 objectively.

症状： 覆盖率仅70%就标记完成，未执行验证命令 修复： 执行所有5项验证检查，必须全部通过。

Failure Mode 6: No State Machines

失败模式6：缺少状态机图表

Symptom: Listing states without visual diagram Fix: Add ASCII diagram + transition table for every entity with states.

症状： 仅列出状态，未提供可视化图表 修复： 为每个含状态的实体添加ASCII图表+转换表。

Quick Workflow Summary

快速工作流总结

PHASE 0: DETECT FRAMEWORK
├── Check composer.json+artisan → Laravel
├── Check next.config.* → Next.js
├── Check nest-cli.json/@nestjs/core → NestJS
├── Check app.json(expo)+_layout.tsx → Expo/React Native
├── Check packages/*/package.json → Node.js monorepo
└── Announce detected framework

PHASE 1: DISCOVERY (framework-specific, do not skip)
├── Scan all classes/files/exports per framework steps
├── Map all routes/screens
├── Identify state machines
└── Create inventory with counts

PHASE 2: DOCUMENTATION (3 required files)
├── CREATE exports-reference.md (>90% coverage, framework tables)
├── CREATE development-guide.md (step-by-step, actual code)
├── CREATE architecture.md (diagrams, routes, flows)
└── UPDATE CLAUDE.md (add @imports, keep <1000 lines)

PHASE 3: VERIFICATION (all must pass)
├── API surface coverage >90%
├── Context budget met (<2500 lines total)
├── All required sections present
├── No duplicates between files
└── AI effectiveness test passes

COMPLETE: Announce final quality score (must be 10/10)

第0阶段：框架检测
├── 检查composer.json+artisan → Laravel
├── 检查next.config.* → Next.js
├── 检查nest-cli.json/@nestjs/core → NestJS
├── 检查app.json(expo)+_layout.tsx → Expo/React Native
├── 检查packages/*/package.json → Node.js monorepo
└── 发布框架检测通知

第1阶段：探索（框架专属，不可跳过）
├── 按框架步骤扫描所有类/文件/导出项
├── 映射所有路由/页面
├── 识别状态机
└── 创建带统计数的清单

第2阶段：文档编写（3个必填文件）
├── 创建exports-reference.md（>90%覆盖率，框架专属表格）
├── 创建development-guide.md（分步指南，真实代码）
├── 创建architecture.md（图表、路由、流程）
└── 更新CLAUDE.md（添加@imports，保持<1000行）

第3阶段：验证（全部必须通过）
├── API表面覆盖率>90%
├── 符合上下文预算（总计<2500行）
├── 所有必填章节完整
├── 文件间无重复内容
└── AI效能测试通过

完成：发布最终质量评分（必须为10/10）

Completion Announcement

完成通知模板

Documentation update complete.

**Framework:** [Laravel/Next.js/NestJS/Expo/Node.js monorepo]

**Quality Score: X/10**
- API Surface Coverage: X/2 (Y% of Z items documented)
- Implementation Guidance: X/2
- State/Workflow Diagrams: X/2
- Routes/Screens: X/2
- Context Efficiency: X/2

**Files created/updated:**
- exports-reference.md: X lines
- development-guide.md: X lines
- architecture.md: X lines
- CLAUDE.md: X lines
- Total: X lines (within 2,500 budget)

**Verification passed:** All 5 checks complete.

This skill ensures documentation enables AI agents to implement features correctly on the first attempt — across Laravel, Next.js, NestJS, Expo/React Native, and Node.js monorepo projects.

文档更新完成。

**框架：** [Laravel/Next.js/NestJS/Expo/Node.js monorepo]

**质量评分：X/10**
- API表面覆盖率：X/2（已记录Z项中的Y%）
- 实现指导：X/2
- 状态/工作流图表：X/2
- 路由/页面：X/2
- 上下文效率：X/2

**创建/更新的文件：**
- exports-reference.md：X行
- development-guide.md：X行
- architecture.md：X行
- CLAUDE.md：X行
- 总计：X行（符合2500行预算）

**验证状态：** 所有5项检查已完成并通过。

本技能确保文档能让AI Agent首次尝试就正确实现功能 —— 支持Laravel、Next.js、NestJS、Expo/React Native和Node.js monorepo项目。

map-project

Original

Translation

Update CLAUDE.md After Installation

安装后更新CLAUDE.md

MANDATORY FIRST RESPONSE PROTOCOL

强制首响应协议

Overview

概述

Context Budget Limits

上下文预算限制

If Over Budget

超出预算时的处理

What Makes 10/10 Documentation

何为10/10质量的文档

1. Step-by-Step Implementation Guides

1. 分步实现指南

Adding a New API Endpoint (Laravel)

添加新API端点（Laravel）

Step 1: Create the Model

步骤1：创建模型

Step 2: Create the Form Request

步骤2：创建表单请求

Step 3: Create the Controller (thin — delegates to Service)

步骤3：创建控制器（轻量型 —— 委托给Service）

Step 4: Register Routes in routes/api.php

步骤4：在routes/api.php中注册路由

2. Response Formats

2. 响应格式

3. State Machines with Visual Diagrams

3. 状态机与可视化图表

Gift Redemption State Machine

礼品兑换状态机

4. Route/Screen Tables

4. 路由/页面表格

5. API Surface Tables

5. API表面表格

When to Use

使用场景

Common Rationalizations (All Wrong)

常见错误合理化借口（全错）

Phase 0: Framework Detection (MANDATORY)

第0阶段：框架检测（强制）

Phase 1: Exhaustive Discovery (MANDATORY)

第1阶段：全面探索（强制）

Laravel

Laravel

Next.js (App Router)

Next.js（App Router）

NestJS

NestJS

Expo/React Native (expo-router)

Expo/React Native（expo-router）

Node.js Monorepo

Node.js Monorepo

Inventory Checklist (all frameworks)

清单检查（所有框架）

Phase 2: Required Output Files

第2阶段：必填输出文件

File 1: exports-reference.md (REQUIRED)

文件1：exports-reference.md（必填）

Laravel

Laravel

Next.js

Next.js

NestJS

NestJS

Expo/React Native

Expo/React Native

Node.js Monorepo

Node.js Monorepo

File 2: development-guide.md (REQUIRED)

文件2：development-guide.md（必填）

File 3: architecture.md (REQUIRED)

文件3：architecture.md（必填）

File 4: Update CLAUDE.md

文件4：更新CLAUDE.md

Project Documentation

项目文档

Quick Documentation Reference

File 1:
`exports-reference.md`
(REQUIRED)

文件1：
`exports-reference.md`
（必填）

File 2:
`development-guide.md`
(REQUIRED)

文件2：
`development-guide.md`
（必填）

File 3:
`architecture.md`
(REQUIRED)

文件3：
`architecture.md`
（必填）

File 4: Update
`CLAUDE.md`

文件4：更新
`CLAUDE.md`