name: clean-code description: Pragmatic coding standards - concise, direct, no over-engineering, no unnecessary comments tools: Read, Write, Edit version: 1.0 priority: CRITICAL

Clean Code - Pragmatic AI Coding Standards

CRITICAL SKILL - This skill overrides all verbose tendencies. When writing code, be concise, direct, and solution-focused.

Golden Rules

1. No Verbose Explanations

WRONG:

// Check if user is authenticated before allowing access to protected route
// This is a security measure to prevent unauthorized access
if (user.isAuthenticated) {
  // User is authenticated, grant access
  return renderProtectedPage();
} else {
  // User is not authenticated, redirect to login
  return redirect('/login');
}

RIGHT:

if (!user.isAuthenticated) return redirect('/login');
return renderProtectedPage();

2. No Self-Explanatory Comments

Code should be self-documenting. If you need a comment, rename the variable.

WRONG:

// Get all users from database
const users = db.get('users');

// Filter out inactive users
const active = users.filter(u => u.active);

RIGHT:

const activeUsers = db.get('users').filter(u => u.active);

3. Direct Solutions Only

WRONG:

// First, let's create a helper function to handle the case where
// we need to check if a value exists in the array...
function hasValue(arr, val) {
  return arr.includes(val);
}

// Now we can use it
if (hasValue(users, id)) {
  // ...
}

RIGHT:

if (users.includes(id)) { /* ... */ }

When to Write Code

Write Code When:

User asks for a feature → Write the feature, not a planning document
User reports a bug → Fix it, don't explain the debugging process
User asks "how does X work" → Brief explanation, then move on

Don't Write Code When:

User only asks "what do you think?"
User is exploring ideas (use brainstorming mode)
No clear requirement exists (ask, don't assume)

Anti-Patterns to Avoid

Anti-Pattern	Example	Fix
Over-commenting	Comment every line	Delete obvious comments
Over-abstracting	Helper for one-line operation	Inline the code
Over-engineering	Factory for 2 objects	Direct instantiation
Defensive coding	Check for impossible null	Remove dead code
Tutorial-style	"First we import..."	Just write the code
Yoda conditions	`if (null === x)`	`if (x === null)`
Early returns	Deep nesting	Guard clauses

Code Style Guidelines

JavaScript/TypeScript

// Prefer concise patterns
const result = data?.map(x => x.value).filter(Boolean) ?? [];

// Guard clauses
if (!user) return unauthorized();

// Direct returns
return isValid ? success() : error();

// No unnecessary intermediates
return items.filter(x => x.active).map(x => x.id);

Python

# Concise, pythonic
active_users = [u for u in users if u.is_active]

# Guard clauses
if not request.user.is_authenticated:
    return HttpResponseForbidden()

# Direct returns
return JsonResponse({"data": result})

React/Next.js

// Direct, no prop drilling abstractions
export default function UserProfile({ user }: { user: User }) {
  if (!user) return <LoginPrompt />;
  return <ProfileData user={user} />;
}

// No separate container components
// No unnecessary HOCs
// Use hooks directly

What NOT to Do

Never Add These Comments:

❌ "This function returns..."
❌ "We need to import..."
❌ "Now let's create..."
❌ "This is a React component..."
❌ "Here we are handling..."
❌ "Note that..."
❌ "TODO: add error handling" (add it or don't mention it)

Never Add These Files:

❌ utils.ts with one function
❌ constants.ts with 3 values
❌ types.ts for one interface
❌ Separate container/ and components/ without reason

Practical Examples

Example 1: API Handler

Verbose (BAD):

// Import the express framework for handling HTTP requests
import express from 'express';

// Create a new router instance
const router = express.Router();

/**
 * GET /api/users
 * Returns a list of all users in the database
 */
router.get('/users', async (req, res) => {
  try {
    // Fetch all users from database
    const users = await db.users.findMany();

    // Return the users as JSON
    res.json({ users });
  } catch (error) {
    // If there's an error, log it and return 500
    console.error(error);
    res.status(500).json({ error: 'Server error' });
  }
});

Concise (GOOD):

import express from 'express';

const router = express.Router();

router.get('/users', async (req, res) => {
  const users = await db.users.findMany();
  res.json({ users });
});

Example 2: React Component

Verbose (BAD):

// This is a functional component that displays a user card
// It takes a user object as a prop and renders the user's information
interface UserCardProps {
  user: User;
}

export const UserCard: React.FC<UserCardProps> = ({ user }) => {
  // If there's no user, show a loading state
  if (!user) {
    return <div>Loading...</div>;
  }

  // Render the user card with name and email
  return (
    <div className="user-card">
      <h2>{user.name}</h2>
      <p>{user.email}</p>
    </div>
  );
};

Concise (GOOD):

export function UserCard({ user }: { user: User }) {
  if (!user) return <div>Loading...</div>;

  return (
    <div className="user-card">
      <h2>{user.name}</h2>
      <p>{user.email}</p>
    </div>
  );
}

Quick Checklist Before Writing

Ask yourself:

Is this code necessary? → If no, don't write it
Can this be simpler? → Simplify it
Am I explaining obvious things? → Delete the explanation
Is there a shorter way? → Use it
Am I creating files for no reason? → Put code inline

Response Format

When asked to write code, respond like this:

[Direct code block]

[Brief explanation if needed, max 2 sentences]

NOT like this:

[Step-by-step tutorial]
[Multiple code blocks with explanations]
[File-by-file breakdown]

Summary

Do	Don't
Write code directly	Write tutorials
Use concise syntax	Use verbose patterns
Let code self-document	Add obvious comments
Fix bugs immediately	Explain the fix first
Return early	Deep nesting
Inline small things	Create unnecessary files
Use language idioms	Force patterns

Remember: The user wants working code, not a programming lesson.

clean-code

Installation

Details

Usage

Skill Instructions

name: clean-code description: Pragmatic coding standards - concise, direct, no over-engineering, no unnecessary comments tools: Read, Write, Edit version: 1.0 priority: CRITICAL

Clean Code - Pragmatic AI Coding Standards

Golden Rules

1. No Verbose Explanations

2. No Self-Explanatory Comments

3. Direct Solutions Only

When to Write Code

Write Code When:

Don't Write Code When:

Anti-Patterns to Avoid

Code Style Guidelines

JavaScript/TypeScript

Python

React/Next.js

What NOT to Do

Never Add These Comments:

Never Add These Files:

Practical Examples

Example 1: API Handler

Example 2: React Component

Quick Checklist Before Writing

Response Format

Summary

More by xenitV1