PaperclipOrg
Claude Agent Skill · by Affaan M

Coding Standards

Your foundation layer for cross-language coding conventions that actually stick. Enforces immutability patterns, descriptive naming, proper error handling, and

Install
Terminal · npx
$npx skills add https://github.com/affaan-m/everything-claude-code --skill coding-standards
Works with Paperclip

How Coding Standards fits into a Paperclip company.

Coding Standards drops into any Paperclip agent that handles this kind of work. Assign it to a specialist inside a pre-configured PaperclipOrg company and the skill becomes available on every heartbeat — no prompt engineering, no tool wiring.

S
SaaS FactoryPaired

Pre-configured AI company — 18 agents, 18 skills, one-time purchase.

$27$59
Explore pack
Source file
SKILL.md549 lines
Expand
---name: coding-standardsdescription: Baseline cross-project coding conventions for naming, readability, immutability, and code-quality review. Use detailed frontend or backend skills for framework-specific patterns.origin: ECC--- # Coding Standards & Best Practices Baseline coding conventions applicable across projects. This skill is the shared floor, not the detailed framework playbook. - Use `frontend-patterns` for React, state, forms, rendering, and UI architecture.- Use `backend-patterns` or `api-design` for repository/service layers, endpoint design, validation, and server-specific concerns.- Use `rules/common/coding-style.md` when you need the shortest reusable rule layer instead of a full skill walkthrough. ## When to Activate - Starting a new project or module- Reviewing code for quality and maintainability- Refactoring existing code to follow conventions- Enforcing naming, formatting, or structural consistency- Setting up linting, formatting, or type-checking rules- Onboarding new contributors to coding conventions ## Scope Boundaries Activate this skill for:- descriptive naming- immutability defaults- readability, KISS, DRY, and YAGNI enforcement- error-handling expectations and code-smell review Do not use this skill as the primary source for:- React composition, hooks, or rendering patterns- backend architecture, API design, or database layering- domain-specific framework guidance when a narrower ECC skill already exists ## Code Quality Principles ### 1. Readability First- Code is read more than written- Clear variable and function names- Self-documenting code preferred over comments- Consistent formatting ### 2. KISS (Keep It Simple, Stupid)- Simplest solution that works- Avoid over-engineering- No premature optimization- Easy to understand > clever code ### 3. DRY (Don't Repeat Yourself)- Extract common logic into functions- Create reusable components- Share utilities across modules- Avoid copy-paste programming ### 4. YAGNI (You Aren't Gonna Need It)- Don't build features before they're needed- Avoid speculative generality- Add complexity only when required- Start simple, refactor when needed ## TypeScript/JavaScript Standards ### Variable Naming ```typescript// PASS: GOOD: Descriptive namesconst marketSearchQuery = 'election'const isUserAuthenticated = trueconst totalRevenue = 1000 // FAIL: BAD: Unclear namesconst q = 'election'const flag = trueconst x = 1000``` ### Function Naming ```typescript// PASS: GOOD: Verb-noun patternasync function fetchMarketData(marketId: string) { }function calculateSimilarity(a: number[], b: number[]) { }function isValidEmail(email: string): boolean { } // FAIL: BAD: Unclear or noun-onlyasync function market(id: string) { }function similarity(a, b) { }function email(e) { }``` ### Immutability Pattern (CRITICAL) ```typescript// PASS: ALWAYS use spread operatorconst updatedUser = {  ...user,  name: 'New Name'} const updatedArray = [...items, newItem] // FAIL: NEVER mutate directlyuser.name = 'New Name'  // BADitems.push(newItem)     // BAD``` ### Error Handling ```typescript// PASS: GOOD: Comprehensive error handlingasync function fetchData(url: string) {  try {    const response = await fetch(url)     if (!response.ok) {      throw new Error(`HTTP ${response.status}: ${response.statusText}`)    }     return await response.json()  } catch (error) {    console.error('Fetch failed:', error)    throw new Error('Failed to fetch data')  }} // FAIL: BAD: No error handlingasync function fetchData(url) {  const response = await fetch(url)  return response.json()}``` ### Async/Await Best Practices ```typescript// PASS: GOOD: Parallel execution when possibleconst [users, markets, stats] = await Promise.all([  fetchUsers(),  fetchMarkets(),  fetchStats()]) // FAIL: BAD: Sequential when unnecessaryconst users = await fetchUsers()const markets = await fetchMarkets()const stats = await fetchStats()``` ### Type Safety ```typescript// PASS: GOOD: Proper typesinterface Market {  id: string  name: string  status: 'active' | 'resolved' | 'closed'  created_at: Date} function getMarket(id: string): Promise<Market> {  // Implementation} // FAIL: BAD: Using 'any'function getMarket(id: any): Promise<any> {  // Implementation}``` ## React Best Practices ### Component Structure ```typescript// PASS: GOOD: Functional component with typesinterface ButtonProps {  children: React.ReactNode  onClick: () => void  disabled?: boolean  variant?: 'primary' | 'secondary'} export function Button({  children,  onClick,  disabled = false,  variant = 'primary'}: ButtonProps) {  return (    <button      onClick={onClick}      disabled={disabled}      className={`btn btn-${variant}`}    >      {children}    </button>  )} // FAIL: BAD: No types, unclear structureexport function Button(props) {  return <button onClick={props.onClick}>{props.children}</button>}``` ### Custom Hooks ```typescript// PASS: GOOD: Reusable custom hookexport function useDebounce<T>(value: T, delay: number): T {  const [debouncedValue, setDebouncedValue] = useState<T>(value)   useEffect(() => {    const handler = setTimeout(() => {      setDebouncedValue(value)    }, delay)     return () => clearTimeout(handler)  }, [value, delay])   return debouncedValue} // Usageconst debouncedQuery = useDebounce(searchQuery, 500)``` ### State Management ```typescript// PASS: GOOD: Proper state updatesconst [count, setCount] = useState(0) // Functional update for state based on previous statesetCount(prev => prev + 1) // FAIL: BAD: Direct state referencesetCount(count + 1)  // Can be stale in async scenarios``` ### Conditional Rendering ```typescript// PASS: GOOD: Clear conditional rendering{isLoading && <Spinner />}{error && <ErrorMessage error={error} />}{data && <DataDisplay data={data} />} // FAIL: BAD: Ternary hell{isLoading ? <Spinner /> : error ? <ErrorMessage error={error} /> : data ? <DataDisplay data={data} /> : null}``` ## API Design Standards ### REST API Conventions ```GET    /api/markets              # List all marketsGET    /api/markets/:id          # Get specific marketPOST   /api/markets              # Create new marketPUT    /api/markets/:id          # Update market (full)PATCH  /api/markets/:id          # Update market (partial)DELETE /api/markets/:id          # Delete market # Query parameters for filteringGET /api/markets?status=active&limit=10&offset=0``` ### Response Format ```typescript// PASS: GOOD: Consistent response structureinterface ApiResponse<T> {  success: boolean  data?: T  error?: string  meta?: {    total: number    page: number    limit: number  }} // Success responsereturn NextResponse.json({  success: true,  data: markets,  meta: { total: 100, page: 1, limit: 10 }}) // Error responsereturn NextResponse.json({  success: false,  error: 'Invalid request'}, { status: 400 })``` ### Input Validation ```typescriptimport { z } from 'zod' // PASS: GOOD: Schema validationconst CreateMarketSchema = z.object({  name: z.string().min(1).max(200),  description: z.string().min(1).max(2000),  endDate: z.string().datetime(),  categories: z.array(z.string()).min(1)}) export async function POST(request: Request) {  const body = await request.json()   try {    const validated = CreateMarketSchema.parse(body)    // Proceed with validated data  } catch (error) {    if (error instanceof z.ZodError) {      return NextResponse.json({        success: false,        error: 'Validation failed',        details: error.errors      }, { status: 400 })    }  }}``` ## File Organization ### Project Structure ```src/├── app/                    # Next.js App Router│   ├── api/               # API routes│   ├── markets/           # Market pages│   └── (auth)/           # Auth pages (route groups)├── components/            # React components│   ├── ui/               # Generic UI components│   ├── forms/            # Form components│   └── layouts/          # Layout components├── hooks/                # Custom React hooks├── lib/                  # Utilities and configs│   ├── api/             # API clients│   ├── utils/           # Helper functions│   └── constants/       # Constants├── types/                # TypeScript types└── styles/              # Global styles``` ### File Naming ```components/Button.tsx          # PascalCase for componentshooks/useAuth.ts              # camelCase with 'use' prefixlib/formatDate.ts             # camelCase for utilitiestypes/market.types.ts         # camelCase with .types suffix``` ## Comments & Documentation ### When to Comment ```typescript// PASS: GOOD: Explain WHY, not WHAT// Use exponential backoff to avoid overwhelming the API during outagesconst delay = Math.min(1000 * Math.pow(2, retryCount), 30000) // Deliberately using mutation here for performance with large arraysitems.push(newItem) // FAIL: BAD: Stating the obvious// Increment counter by 1count++ // Set name to user's namename = user.name``` ### JSDoc for Public APIs ```typescript/** * Searches markets using semantic similarity. * * @param query - Natural language search query * @param limit - Maximum number of results (default: 10) * @returns Array of markets sorted by similarity score * @throws {Error} If OpenAI API fails or Redis unavailable * * @example * ```typescript * const results = await searchMarkets('election', 5) * console.log(results[0].name) // "Trump vs Biden" * ``` */export async function searchMarkets(  query: string,  limit: number = 10): Promise<Market[]> {  // Implementation}``` ## Performance Best Practices ### Memoization ```typescriptimport { useMemo, useCallback } from 'react' // PASS: GOOD: Memoize expensive computationsconst sortedMarkets = useMemo(() => {  return markets.sort((a, b) => b.volume - a.volume)}, [markets]) // PASS: GOOD: Memoize callbacksconst handleSearch = useCallback((query: string) => {  setSearchQuery(query)}, [])``` ### Lazy Loading ```typescriptimport { lazy, Suspense } from 'react' // PASS: GOOD: Lazy load heavy componentsconst HeavyChart = lazy(() => import('./HeavyChart')) export function Dashboard() {  return (    <Suspense fallback={<Spinner />}>      <HeavyChart />    </Suspense>  )}``` ### Database Queries ```typescript// PASS: GOOD: Select only needed columnsconst { data } = await supabase  .from('markets')  .select('id, name, status')  .limit(10) // FAIL: BAD: Select everythingconst { data } = await supabase  .from('markets')  .select('*')``` ## Testing Standards ### Test Structure (AAA Pattern) ```typescripttest('calculates similarity correctly', () => {  // Arrange  const vector1 = [1, 0, 0]  const vector2 = [0, 1, 0]   // Act  const similarity = calculateCosineSimilarity(vector1, vector2)   // Assert  expect(similarity).toBe(0)})``` ### Test Naming ```typescript// PASS: GOOD: Descriptive test namestest('returns empty array when no markets match query', () => { })test('throws error when OpenAI API key is missing', () => { })test('falls back to substring search when Redis unavailable', () => { }) // FAIL: BAD: Vague test namestest('works', () => { })test('test search', () => { })``` ## Code Smell Detection Watch for these anti-patterns: ### 1. Long Functions```typescript// FAIL: BAD: Function > 50 linesfunction processMarketData() {  // 100 lines of code} // PASS: GOOD: Split into smaller functionsfunction processMarketData() {  const validated = validateData()  const transformed = transformData(validated)  return saveData(transformed)}``` ### 2. Deep Nesting```typescript// FAIL: BAD: 5+ levels of nestingif (user) {  if (user.isAdmin) {    if (market) {      if (market.isActive) {        if (hasPermission) {          // Do something        }      }    }  }} // PASS: GOOD: Early returnsif (!user) returnif (!user.isAdmin) returnif (!market) returnif (!market.isActive) returnif (!hasPermission) return // Do something``` ### 3. Magic Numbers```typescript// FAIL: BAD: Unexplained numbersif (retryCount > 3) { }setTimeout(callback, 500) // PASS: GOOD: Named constantsconst MAX_RETRIES = 3const DEBOUNCE_DELAY_MS = 500 if (retryCount > MAX_RETRIES) { }setTimeout(callback, DEBOUNCE_DELAY_MS)``` **Remember**: Code quality is not negotiable. Clear, maintainable code enables rapid development and confident refactoring.