<< All versions
Skill v1.0.0
currentLLM-judged scan90/100cavaleiro-ai/cavaleiro-agent-harness/coding-standards
──Details
PublishedOctober 24, 2026 at 11:30 AM
Content Hashsha256:e80544c3d1eac5b1...
Git SHAac17b561d162
──Files
Files (1 file, 12.6 KB)
SKILL.md12.6 KBactive
SKILL.md · 553 lines · 12.6 KB
version: "1.0.0" name: coding-standards description: Baseline cross-project coding conventions for naming, readability, immutability, and code-quality review. Use detailed frontend or backend skills for framework-specific patterns. Use when reviewing code quality or naming with no framework-specific skill that applies. metadata: 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-patternsfor React, state, forms, rendering, and UI architecture. - Use
backend-patternsorapi-designfor repository/service layers, endpoint design, validation, and server-specific concerns. - Use
rules/common/coding-style.mdwhen 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: stringname: stringstatus: '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.ReactNodeonClick: () => voiddisabled?: booleanvariant?: 'primary' | 'secondary'}export function Button({children,onClick,disabled = false,variant = 'primary'}: ButtonProps) {return (<buttononClick={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: booleandata?: Terror?: stringmeta?: {total: numberpage: numberlimit: 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
typescript
import { 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.issues}, { 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
typescript
import { useMemo, useCallback } from 'react'// PASS: GOOD: Memoize expensive computations// Copy before sorting - Array.prototype.sort mutates in placeconst sortedMarkets = useMemo(() => {return [...markets].sort((a, b) => b.volume - a.volume)}, [markets])// PASS: GOOD: Memoize callbacksconst handleSearch = useCallback((query: string) => {setSearchQuery(query)}, [])
Lazy Loading
typescript
import { 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)
typescript
test('calculates similarity correctly', () => {// Arrangeconst vector1 = [1, 0, 0]const vector2 = [0, 1, 0]// Actconst similarity = calculateCosineSimilarity(vector1, vector2)// Assertexpect(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 = 500if (retryCount > MAX_RETRIES) { }setTimeout(callback, DEBOUNCE_DELAY_MS)
Remember: Code quality is not negotiable. Clear, maintainable code enables rapid development and confident refactoring.