claude-initial-setup AGENTS.md

AGENTS.md

Project Overview

A curated library of 75 Claude Code skills across 25 categories, providing coding standards, patterns, and best practices for software development. Skills cover coding style, git workflow, testing, debugging, security, and language-specific patterns for TypeScript, Python, Go, Rust, Java, React/Next.js, Express/Node, FastAPI, Django, Docker, CI/CD, databases, and more.

Development Conventions

Code Style

Immutability

Always create new objects instead of mutating existing ones. Immutability prevents shared-state bugs and enables reliable change detection.

// WRONG: Mutation
function updateUser(user, name) {
  user.name = name;
  return user;
}

// CORRECT: Immutable update
function updateUser(user, name) {
  return { ...user, name };
}

Array operations must also be immutable:

const added = [...items, newItem];                      // append
const removed = items.filter(x => x.id !== id);         // remove
const updated = items.map(x =>                          // update
  x.id === id ? { ...x, name: "new" } : x
);
const sorted = items.toSorted((a, b) => a.name.localeCompare(b.name));

Python: Use @dataclass(frozen=True) and replace() for immutable data. Go: Use value receivers and return new structs instead of mutating via pointers.

File Organization

• Target 200-400 lines per file, 800 maximum
• Organize by feature/domain, not by type
• Co-locate tests, styles, and types with their source files
• Move code to shared/ only when used by 3+ features

Functions

• Keep functions under 50 lines
• No deep nesting beyond 4 levels
• Name functions with a verb: getUserById, formatDate, validateEmail

Naming

• Variables describe WHAT, not HOW: activeUsers not data
• Booleans use is/has/can/should prefix: isActive, hasPermission
• Collections use plural nouns: users, orderItems
• Constants use SCREAMING_SNAKE: MAX_RETRIES, API_BASE_URL
• Follow language-specific casing (camelCase for JS/TS, snake_case for Python, PascalCase for Go exports)