**Prompt Claude with:**
Generates complete frontend feature from OpenAPI spec using incremental 5-phase workflow.
/plugin marketplace add venturo-id/venturo-claude/plugin install venturo-react@venturo-toolsPrompt Claude with:
Create new feature from OpenAPI, read new-feature-instruction.md
Claude will:
This instruction uses an incremental workflow broken into 5 phases to save context and allow validation at each step.
Incremental phase files are located at: .venturo/instructions/new-feature/
Phase 1: API Layer (01-api-layer.md)
Phase 2: Feature Components (02-feature-components.md)
Phase 3: Feature Hooks (03-feature-hooks.md)
Phase 4: Page Integration & Routes (04-page-and-routes.md)
Phase 5: Permissions & Constants (05-permissions-constants.md)
See: .venturo/instructions/new-feature/README.md for complete incremental workflow details.
When this instruction is invoked, Claude MUST ask these questions:
Question 1: "What is the path to the OpenAPI YAML file?"
/mnt/d/Dev/Venturo/RnD/venturo-skeleton-go/docs/api/openapi-{feature_name}.yaml/mnt/d/Dev/Venturo/RnD/venturo-skeleton-go/docs/api/openapi-customer_management.yamlQuestion 2: "What should the feature name be in the frontend?"
customer_management (snake_case)CustomerManagement or Customercustomer or customer-managementQuestion 3: "What is the base API path for this feature?"
servers.url or paths/core/v1/customersQuestion 4: "Review the OpenAPI spec analysis - does this look correct?" Present a summary showing:
/core/v1/customersQuestion 5: "What components should we generate?" Based on OpenAPI analysis, suggest:
Question 6: "Does this feature need any of these additional features?"
Present a complete implementation plan:
š Feature Implementation Plan
Feature: Customer Management
Entity: Customer
Base Path: /core/v1/customers
šļø Files to Create:
API Layer (src/app/api/customer/):
ā type.ts - TypeScript interfaces
ā customerApi.ts - API endpoint functions
ā useCustomerApi.ts - React Query hooks
ā index.ts - Exports
Feature Components (src/features/customer/components/):
ā CustomerTable.tsx - Data table with pagination
ā CustomerForm.tsx - Create/Edit dialog
ā CustomerFilters.tsx - Search bar and filter button
ā CustomerFilterDrawer.tsx - Advanced filter drawer
Feature Hooks (src/features/customer/hooks/):
ā useTableCustomer.ts - Table state and operations
ā useFormCustomer.ts - Form state and validation
Feature Page (src/features/customer/):
ā CustomerPage.tsx - Main page component
Routes & Constants:
ā Update src/app/routes/Router.tsx
ā Update src/app/routes/SideBarData.ts
ā Update src/app/constants/permission.ts
ā Update src/app/constants/router.ts
Estimated Time: 15-20 minutes
Phases: 5 incremental phases with validation checkpoints
Ask: "Does this plan look correct? Should I proceed with implementation?"
After user confirms the plan, Claude will:
.venturo/instructions/new-feature/01-api-layer.mdUser: Create new feature from OpenAPI, read new-feature-instruction.md
Claude: [Asks for OpenAPI file path]
User: /mnt/d/Dev/Venturo/RnD/venturo-skeleton-go/docs/api/openapi-customer_management.yaml
Claude: [Reads and parses OpenAPI]
[Asks remaining discovery questions]
[Presents complete plan]
User: Yes, proceed
Claude: [Reads .venturo/instructions/new-feature/01-api-layer.md]
[Executes Phase 1: Creates API layer]
ā
Phase 1 Complete: API Layer
Created:
- src/app/api/customer/type.ts
- src/app/api/customer/customerApi.ts
- src/app/api/customer/useCustomerApi.ts
- src/app/api/customer/index.ts
Please review the API layer code, especially:
- TypeScript types match OpenAPI schemas
- API endpoints use correct paths
- React Query hooks have proper cache invalidation
Say "continue" to proceed to Phase 2 (Feature Components).
User: continue
Claude: [Reads .venturo/instructions/new-feature/02-feature-components.md]
[Executes Phase 2: Creates components]
ā
Phase 2 Complete: Feature Components
Created:
- src/features/customer/components/CustomerTable.tsx
- src/features/customer/components/CustomerForm.tsx
- src/features/customer/components/CustomerFilters.tsx
- src/features/customer/components/CustomerFilterDrawer.tsx
Please review the components.
Say "continue" to proceed to Phase 3 (Feature Hooks).
[Process continues through all 5 phases]
1. TypeScript Types from OpenAPI:
// ā
Correct: Match OpenAPI schema exactly
export interface Customer {
id: string;
name: string;
email: string;
phone?: string; // Optional in OpenAPI
address?: string;
status: 'active' | 'inactive'; // Enum from OpenAPI
created_at: string;
updated_at: string;
}
// ā Wrong: Using different field names or types
export interface Customer {
customerId: string; // Should be 'id'
status: string; // Should be enum
}
2. API Service Pattern:
// ā
Correct: Use apiService from @/app/services
import { apiService } from '@/app/services/apiService';
export const customerApi = {
createCustomer: (data: CreateCustomerData) =>
apiService.post<ResponseApi<Customer>>('/core/v1/customers', data),
};
// ā Wrong: Direct axios usage
import axios from 'axios';
axios.post('/core/v1/customers', data);
3. React Query Hooks Pattern:
// ā
Correct: Follow existing pattern with proper typing
export const customerKeys = {
all: ['customers'] as const,
lists: () => [...customerKeys.all, 'list'] as const,
list: (params?: ListCustomersParams) => [...customerKeys.lists(), params] as const,
details: () => [...customerKeys.all, 'detail'] as const,
detail: (id: string) => [...customerKeys.details(), id] as const,
};
export const useGetListCustomers = (
params?: ListCustomersParams,
options?: Omit<UseQueryOptions<AxiosResponse<ResponseApiWithMeta<Customer[]>>, AxiosError>, 'queryKey' | 'queryFn'>
) => {
return useQuery({
queryKey: customerKeys.list(params),
queryFn: () => customerApi.listCustomers(params),
...options,
});
};
// ā Wrong: Not using query keys factory pattern
export const useGetListCustomers = () => {
return useQuery(['customers'], () => customerApi.listCustomers());
};
4. Component Imports:
// ā
Correct: Import from @/shared/components/venturo-ui
import { Box, Button, Typography, Card } from '@/shared/components/venturo-ui';
import { IconPlus } from '@tabler/icons-react';
// ā Wrong: Importing from @mui/material directly
import { Box, Button } from '@mui/material';
5. Permission Checks:
// ā
Correct: Use usePermission hook and constants
import { usePermission } from '@/shared/hooks';
import { PERMISSIONS } from '@/app/constants/permission';
const { hasPermission } = usePermission();
const canCreate = hasPermission(PERMISSIONS.CUSTOMER_CREATE);
// ā Wrong: Hardcoded permission strings
const canCreate = hasPermission('customer.create');
6. File Naming Conventions:
type.ts (in feature API folder){feature}Api.ts (e.g., customerApi.ts)use{Feature}Api.ts (e.g., useCustomerApi.ts){Feature}{Component}.tsx (e.g., CustomerTable.tsx)use{Action}{Feature}.ts (e.g., useTableCustomer.ts){Feature}Page.tsx (e.g., CustomerPage.tsx)Solution: Always use ResponseApi<T> or ResponseApiWithMeta<T>:
// ā
Correct
apiService.get<ResponseApiWithMeta<Customer[]>>('/core/v1/customers')
// ā Wrong
apiService.get<Customer[]>('/core/v1/customers')
Solution: Always invalidate related queries in mutations:
// ā
Correct
export const usePostCustomers = (options?: MutationOptions) => {
const queryClient = useQueryClient();
return useMutation({
mutationFn: customerApi.createCustomer,
onSuccess: (response, ...args) => {
queryClient.invalidateQueries({ queryKey: customerKeys.lists() });
options?.onSuccess?.(response, ...args);
},
...options,
});
};
Solution: Always use @/ or src/ prefix:
// ā
Correct
import { apiService } from '@/app/services/apiService';
// ā Wrong
import { apiService } from '../../../app/services/apiService';
Solution: Use React Query hooks, not local state for server data:
// ā
Correct
const { data, isLoading } = useGetListCustomers(params);
const customers = data?.data?.data || [];
// ā Wrong
const [customers, setCustomers] = useState([]);
useEffect(() => {
fetchCustomers().then(setCustomers);
}, []);
Solution: Always check permissions before rendering actions:
// ā
Correct
{canCreate && (
<Button onClick={handleCreate}>Add Customer</Button>
)}
// ā Wrong
<Button onClick={handleCreate}>Add Customer</Button>
After all phases complete, verify:
npm run type-check)npm run lint)npm run format)After implementation, test the feature manually:
Start the development server:
npm run dev
Navigate to the feature page:
/customers)Test CRUD Operations:
Test Filters:
Test Pagination:
Test Permissions:
Test Error Handling:
User: Create new feature from OpenAPI, read new-feature-instruction.md
Claude: I'll help you create a new frontend feature from an OpenAPI specification.
Let me start by asking some questions:
1. What is the path to the OpenAPI YAML file?
User: /mnt/d/Dev/Venturo/RnD/venturo-skeleton-go/docs/api/openapi-customer_management.yaml
Claude: [Reads and parses the OpenAPI file]
Great! I've analyzed the OpenAPI spec. Here's what I found:
Feature: customer_management
Entity: Customer
Base Path: /core/v1/customers
Endpoints:
- POST /customers (Create)
- GET /customers (List)
- GET /customers/{id} (Get by ID)
- PUT /customers/{id} (Update)
- DELETE /customers/{id} (Delete)
2. What should the feature name be in the frontend?
Suggestion: "customer" (lowercase for files, Customer for components)
User: customer
Claude: [Continues with remaining questions, presents plan, executes phases]