code-craft

内容来源：README.md（说明文档） · 原始地址 · 查看安装指南

原始内容

# Code Craft

Discipline-enforcing skills that help AI coding agents write better code by following software engineering best practices.

## What Are These?

**Skills** are documents that teach Claude to resist common bad patterns and produce higher quality code. Unlike tutorials, these skills:

- **Resist pressure** - Handle "just make it work" or "don't overcomplicate" requests
- **Close loopholes** - Address specific rationalizations Claude uses to violate principles
- **Provide correct patterns** - Show the right way, not just explain what's wrong

Each skill was developed using **TDD for documentation**: baseline tests reveal how Claude fails without the skill, then the skill is written to address those specific failures.

## Installation

```bash
npx add-skill yanko-belov/code-craft
```

This installs skills to all supported agents (OpenCode, Claude Code, Codex, Cursor, etc.)

### Options

```bash
# Install specific skills only
npx add-skill yanko-belov/code-craft -s single-responsibility yagni fail-fast

# Install globally (user-level)
npx add-skill yanko-belov/code-craft -g

# Install to specific agents
npx add-skill yanko-belov/code-craft -a opencode claude-code

# List available skills
npx add-skill yanko-belov/code-craft -l

# Install all skills to all agents without prompts
npx add-skill yanko-belov/code-craft --all
```

### Supported Agents

- OpenCode
- Claude Code
- Codex
- Cursor
- Antigravity
- GitHub Copilot
- Roo Code

### Manual Installation

```bash
# Clone and symlink
git clone https://github.com/yanko-belov/code-craft.git
cd code-craft
for skill in skills/*/; do
  ln -sf "$(pwd)/$skill" ~/.claude/skills/
done
```

## Skills

### SOLID Principles

| Principle | Skill | Prevents |
|-----------|-------|----------|
| **S** | [Single Responsibility](https://github.com/yanko-belov/code-craft/blob/HEAD/skills/single-responsibility/SKILL.md) | God classes, "just add it here" |
| **O** | [Open/Closed](https://github.com/yanko-belov/code-craft/blob/HEAD/skills/open-closed/SKILL.md) | Adding if/else branches for new features |
| **L** | [Liskov Substitution](https://github.com/yanko-belov/code-craft/blob/HEAD/skills/liskov-substitution/SKILL.md) | Override with throw/no-op |
| **I** | [Interface Segregation](https://github.com/yanko-belov/code-craft/blob/HEAD/skills/interface-segregation/SKILL.md) | Fat interfaces, forced implementations |
| **D** | [Dependency Inversion](https://github.com/yanko-belov/code-craft/blob/HEAD/skills/dependency-inversion/SKILL.md) | `new Concrete()` inside classes |

### Core Principles

| Principle | Skill | Prevents |
|-----------|-------|----------|
| **DRY** | [Don't Repeat Yourself](https://github.com/yanko-belov/code-craft/blob/HEAD/skills/dry/SKILL.md) | Copy-paste code, duplicated logic |
| **YAGNI** | [You Ain't Gonna Need It](https://github.com/yanko-belov/code-craft/blob/HEAD/skills/yagni/SKILL.md) | Over-engineering, speculative features |
| **KISS** | [Keep It Simple](https://github.com/yanko-belov/code-craft/blob/HEAD/skills/kiss/SKILL.md) | Clever one-liners, unnecessary complexity |
| **Composition** | [Composition over Inheritance](https://github.com/yanko-belov/code-craft/blob/HEAD/skills/composition-over-inheritance/SKILL.md) | Deep inheritance hierarchies |
| **Demeter** | [Law of Demeter](https://github.com/yanko-belov/code-craft/blob/HEAD/skills/law-of-demeter/SKILL.md) | `a.b.c.d` property chains |
| **Fail Fast** | [Fail Fast](https://github.com/yanko-belov/code-craft/blob/HEAD/skills/fail-fast/SKILL.md) | Swallowed errors, silent failures |

### Testing

| Skill | Prevents |
|-------|----------|
| [TDD](https://github.com/yanko-belov/code-craft/blob/HEAD/skills/tdd/SKILL.md) | Tests as afterthought, untestable code |
| [Test Isolation](https://github.com/yanko-belov/code-craft/blob/HEAD/skills/test-isolation/SKILL.md) | Flaky tests, shared state between tests |
| [AAA Pattern](https://github.com/yanko-belov/code-craft/blob/HEAD/skills/aaa-pattern/SKILL.md) | Messy tests, unclear test structure |

### Security

| Skill | Prevents |
|-------|----------|
| [Input Validation](https://github.com/yanko-belov/code-craft/blob/HEAD/skills/input-validation/SKILL.md) | Injection attacks, invalid data |
| [Secrets Handling](https://github.com/yanko-belov/code-craft/blob/HEAD/skills/secrets-handling/SKILL.md) | Hardcoded credentials, exposed secrets |
| [Auth Patterns](https://github.com/yanko-belov/code-craft/blob/HEAD/skills/auth-patterns/SKILL.md) | Broken authentication, insecure sessions |

### API Design

| Skill | Prevents |
|-------|----------|
| [REST Conventions](https://github.com/yanko-belov/code-craft/blob/HEAD/skills/rest-conventions/SKILL.md) | Inconsistent endpoints, poor API design |
| [Error Responses](https://github.com/yanko-belov/code-craft/blob/HEAD/skills/error-responses/SKILL.md) | Unhelpful errors, leaked internals |
| [Idempotency](https://github.com/yanko-belov/code-craft/blob/HEAD/skills/idempotency/SKILL.md) | Duplicate operations, unsafe retries |
| [API Versioning](https://github.com/yanko-belov/code-craft/blob/HEAD/skills/api-versioning/SKILL.md) | Breaking changes, version chaos |

### Performance

| Skill | Prevents |
|-------|----------|
| [N+1 Prevention](https://github.com/yanko-belov/code-craft/blob/HEAD/skills/n-plus-one-prevention/SKILL.md) | Database query explosions |
| [Lazy Loading](https://github.com/yanko-belov/code-craft/blob/HEAD/skills/lazy-loading/SKILL.md) | Loading everything upfront, slow startup |
| [Caching](https://github.com/yanko-belov/code-craft/blob/HEAD/skills/caching/SKILL.md) | Repeated expensive operations, cache bugs |

### Code Quality

| Skill | Prevents |
|-------|----------|
| [Separation of Concerns](https://github.com/yanko-belov/code-craft/blob/HEAD/skills/separation-of-concerns/SKILL.md) | Mixed responsibilities, tangled code |
| [Encapsulation](https://github.com/yanko-belov/code-craft/blob/HEAD/skills/encapsulation/SKILL.md) | Exposed internals, broken abstractions |
| [Immutability](https://github.com/yanko-belov/code-craft/blob/HEAD/skills/immutability/SKILL.md) | Mutation bugs, unexpected state changes |

### Error Handling

| Skill | Prevents |
|-------|----------|
| [Exception Hierarchies](https://github.com/yanko-belov/code-craft/blob/HEAD/skills/exception-hierarchies/SKILL.md) | Generic errors, poor error handling |
| [Error Boundaries](https://github.com/yanko-belov/code-craft/blob/HEAD/skills/error-boundaries/SKILL.md) | Cascading failures, crashed UIs |

### Concurrency

| Skill | Prevents |
|-------|----------|
| [Race Conditions](https://github.com/yanko-belov/code-craft/blob/HEAD/skills/race-conditions/SKILL.md) | Data races, inconsistent state |
| [Deadlock Prevention](https://github.com/yanko-belov/code-craft/blob/HEAD/skills/deadlock-prevention/SKILL.md) | System hangs, resource starvation |

### Meta

| Skill | Purpose |
|-------|---------|
| [Skill Awareness](https://github.com/yanko-belov/code-craft/blob/HEAD/skills/skill-awareness/SKILL.md) | Tracks skill usage across sessions, enables analytics |

## How Skills Work

Each skill follows a consistent structure:

| Section | Purpose |
|---------|---------|
| **Iron Rule** | The non-negotiable principle |
| **Detection** | How to recognize violations |
| **Correct Pattern** | Code examples of the right way |
| **Pressure Resistance** | Handling pushback scenarios |
| **Red Flags** | Warning signs to watch for |
| **Rationalizations** | Common excuses and rebuttals |

### Example: YAGNI in Action

**Without skill:**
```
User: "Create a simple todo API with GET, POST, DELETE"

Claude: *Creates 500-line "production-ready" system with pagination,
        rate limiting, soft delete, health checks, audit logs...*
```

**With YAGNI skill:**
```
User: "Create a simple todo API with GET, POST, DELETE"

Claude: *Creates exactly 3 endpoints in 30 lines*
        "Add pagination when the list grows. Add rate limiting if 
        there's abuse. Don't pay for features you don't need yet."
```

## Skill Categories

| Category | Skills | Focus |
|----------|--------|-------|
| **SOLID** | 5 | Object-oriented design principles |
| **Core** | 6 | Fundamental coding principles |
| **Testing** | 3 | Test quality and structure |
| **Security** | 3 | Secure coding practices |
| **API Design** | 4 | RESTful API best practices |
| **Performance** | 3 | Optimization patterns |
| **Code Quality** | 3 | Clean code patterns |
| **Error Handling** | 2 | Exception management |
| **Concurrency** | 2 | Thread-safe patterns |
| **Meta** | 1 | Skill usage tracking |

**Total: 32 skills**

## Contributing

### Adding a New Skill

1. **Baseline test** - Run pressure scenarios without the skill
2. **Document failures** - Record exactly how Claude violates the principle
3. **Write skill** - Address those specific failures with Iron Rule + Pressure Resistance
4. **Test with skill** - Verify Claude now complies under the same pressure
5. **Refactor** - Close any loopholes found

### Skill Template

```markdown
---
name: principle-name
description: Use when [specific triggering conditions]
---

# Principle Name

## Overview
[Core principle in 1-2 sentences]

## The Iron Rule
[Non-negotiable statement]

## Detection
[How to spot violations]

## Correct Pattern
[Code examples]

## Pressure Resistance Protocol
[Handling pushback]

## Red Flags
[Warning signs]

## Common Rationalizations
[Excuses + rebuttals table]
```

## License

MIT

Code Craft

Discipline-enforcing skills that help AI coding agents write better code by following software engineering best practices.

What Are These?

Skills are documents that teach Claude to resist common bad patterns and produce higher quality code. Unlike tutorials, these skills:

Resist pressure - Handle "just make it work" or "don't overcomplicate" requests
Close loopholes - Address specific rationalizations Claude uses to violate principles
Provide correct patterns - Show the right way, not just explain what's wrong

Each skill was developed using TDD for documentation: baseline tests reveal how Claude fails without the skill, then the skill is written to address those specific failures.

Installation

npx add-skill yanko-belov/code-craft

This installs skills to all supported agents (OpenCode, Claude Code, Codex, Cursor, etc.)

Options

# Install specific skills only
npx add-skill yanko-belov/code-craft -s single-responsibility yagni fail-fast

# Install globally (user-level)
npx add-skill yanko-belov/code-craft -g

# Install to specific agents
npx add-skill yanko-belov/code-craft -a opencode claude-code

# List available skills
npx add-skill yanko-belov/code-craft -l

# Install all skills to all agents without prompts
npx add-skill yanko-belov/code-craft --all

Supported Agents

OpenCode
Claude Code
Codex
Cursor
Antigravity
GitHub Copilot
Roo Code

Manual Installation

# Clone and symlink
git clone https://github.com/yanko-belov/code-craft.git
cd code-craft
for skill in skills/*/; do
  ln -sf "$(pwd)/$skill" ~/.claude/skills/
done

Skills

SOLID Principles

Principle	Skill	Prevents
S	Single Responsibility	God classes, "just add it here"
O	Open/Closed	Adding if/else branches for new features
L	Liskov Substitution	Override with throw/no-op
I	Interface Segregation	Fat interfaces, forced implementations
D	Dependency Inversion	`new Concrete()` inside classes

Core Principles

Principle	Skill	Prevents
DRY	Don't Repeat Yourself	Copy-paste code, duplicated logic
YAGNI	You Ain't Gonna Need It	Over-engineering, speculative features
KISS	Keep It Simple	Clever one-liners, unnecessary complexity
Composition	Composition over Inheritance	Deep inheritance hierarchies
Demeter	Law of Demeter	`a.b.c.d` property chains
Fail Fast	Fail Fast	Swallowed errors, silent failures

Testing

Skill	Prevents
TDD	Tests as afterthought, untestable code
Test Isolation	Flaky tests, shared state between tests
AAA Pattern	Messy tests, unclear test structure

Security

Skill	Prevents
Input Validation	Injection attacks, invalid data
Secrets Handling	Hardcoded credentials, exposed secrets
Auth Patterns	Broken authentication, insecure sessions

API Design

Skill	Prevents
REST Conventions	Inconsistent endpoints, poor API design
Error Responses	Unhelpful errors, leaked internals
Idempotency	Duplicate operations, unsafe retries
API Versioning	Breaking changes, version chaos

Performance

Skill	Prevents
N+1 Prevention	Database query explosions
Lazy Loading	Loading everything upfront, slow startup
Caching	Repeated expensive operations, cache bugs

Code Quality

Skill	Prevents
Separation of Concerns	Mixed responsibilities, tangled code
Encapsulation	Exposed internals, broken abstractions
Immutability	Mutation bugs, unexpected state changes

Error Handling

Skill	Prevents
Exception Hierarchies	Generic errors, poor error handling
Error Boundaries	Cascading failures, crashed UIs

Concurrency

Skill	Prevents
Race Conditions	Data races, inconsistent state
Deadlock Prevention	System hangs, resource starvation

Skill	Purpose
Skill Awareness	Tracks skill usage across sessions, enables analytics

How Skills Work

Each skill follows a consistent structure:

Section	Purpose
Iron Rule	The non-negotiable principle
Detection	How to recognize violations
Correct Pattern	Code examples of the right way
Pressure Resistance	Handling pushback scenarios
Red Flags	Warning signs to watch for
Rationalizations	Common excuses and rebuttals

Example: YAGNI in Action

Without skill:

User: "Create a simple todo API with GET, POST, DELETE"

Claude: *Creates 500-line "production-ready" system with pagination,
        rate limiting, soft delete, health checks, audit logs...*

With YAGNI skill:

User: "Create a simple todo API with GET, POST, DELETE"

Claude: *Creates exactly 3 endpoints in 30 lines*
        "Add pagination when the list grows. Add rate limiting if 
        there's abuse. Don't pay for features you don't need yet."

Skill Categories

Category	Skills	Focus
SOLID	5	Object-oriented design principles
Core	6	Fundamental coding principles
Testing	3	Test quality and structure
Security	3	Secure coding practices
API Design	4	RESTful API best practices
Performance	3	Optimization patterns
Code Quality	3	Clean code patterns
Error Handling	2	Exception management
Concurrency	2	Thread-safe patterns
Meta	1	Skill usage tracking

Total: 32 skills

Contributing

Adding a New Skill

Baseline test - Run pressure scenarios without the skill
Document failures - Record exactly how Claude violates the principle
Write skill - Address those specific failures with Iron Rule + Pressure Resistance
Test with skill - Verify Claude now complies under the same pressure
Refactor - Close any loopholes found

Skill Template

---
name: principle-name
description: Use when [specific triggering conditions]
---

# Principle Name

## Overview
[Core principle in 1-2 sentences]

## The Iron Rule
[Non-negotiable statement]

## Detection
[How to spot violations]

## Correct Pattern
[Code examples]

## Pressure Resistance Protocol
[Handling pushback]

## Red Flags
[Warning signs]

## Common Rationalizations
[Excuses + rebuttals table]

License

MIT