engineering-code

Category: Development & Coding | Uploader: kinkinluo | Downloads: 0 | Version: v1.0（Latest）

This skill produces modular, well-structured code for general software projects that need to stay maintainable across long conversations and repeated iteration.

Changelog: Source: GitHub https://github.com/kinkinluo/kinkinluo-skills

Directory Structure

Current level: skills/engineering-code/

📁 references/
- 📄 naming.md 6.1 KB
- 📄 patterns.md 11.1 KB
- 📄 templates.md 11.3 KB
📄 SKILL.md 5.7 KB

SKILL.md

---
name: engineering-code
description: |
  Use this skill for general software engineering work where maintainable structure is the priority: starting or refactoring backend, frontend, library, CLI, or app codebases; splitting large files into focused modules; defining clear interfaces; or setting up a project that will evolve over multiple turns. Prefer it for readable, testable, reusable product code. If the task is specifically ML training infrastructure, distributed experiment systems, or strict model reproduction, use the more specialized skill instead.
---

# Engineering Code

This skill produces modular, well-structured code for general software projects that need to stay maintainable across long conversations and repeated iteration.

## Core Principle: Modular by Default

**Every file should have ONE clear responsibility.** This enables:
- Understanding code without loading entire project
- Modifying one feature without touching others
- Reusing components across projects
- Continuing development across conversation turns

## Project Initialization

When starting a new project:

1. **Determine project type** → Select appropriate template from `references/templates.md`
2. **Create directory structure first** → Establish skeleton before writing code
3. **Define interfaces early** → Specify how modules communicate

## File Size Rules

| File Type | Max Lines | Action if Exceeded |
|-----------|-----------|-------------------|
| Module/Component | 150 | Split by responsibility |
| Utility file | 100 | Group related utils separately |
| Type definitions | 200 | Split by domain |
| Test file | 200 | One test file per module |
| Config file | 50 | Use config composition |

## Module Design Pattern

Every module follows this structure:

```
module/
├── index.ts          # Public exports only
├── types.ts          # Interfaces and types
├── [name].ts         # Core implementation
├── [name].test.ts    # Tests
└── utils.ts          # Internal helpers (optional)
```

**index.ts pattern** - Only re-exports, no logic:
```typescript
export { UserService } from './user-service';
export type { User, UserConfig } from './types';
```

## Interface-First Development

Before implementing any feature:

1. **Define the interface** in `types.ts`
2. **Write usage example** in comments
3. **Then implement**

This ensures clear contracts between modules.

## Naming Conventions

See `references/naming.md` for comprehensive conventions. Key rules:

- Files: `kebab-case.ts` (e.g., `user-service.ts`)
- Classes/Types: `PascalCase`
- Functions/Variables: `camelCase`
- Constants: `UPPER_SNAKE_CASE`
- Test files: `[name].test.ts` or `[name].spec.ts`

## Project Structure by Type

See `references/templates.md` for complete templates. Quick reference:

**Backend API:**
```
src/
├── modules/           # Feature modules
│   └── [feature]/
├── shared/            # Cross-cutting concerns
│   ├── types/
│   ├── utils/
│   └── middleware/
├── config/            # Configuration
└── index.ts           # Entry point
```

**Frontend App:**
```
src/
├── components/        # UI components
│   └── [Component]/
├── hooks/             # Custom hooks
├── services/          # API/business logic
├── types/             # Shared types
└── utils/             # Helpers
```

**Library/Package:**
```
src/
├── core/              # Core functionality
├── types/             # Public types
├── utils/             # Internal utilities
└── index.ts           # Public API
```

## Code Organization Rules

### Imports
Order imports consistently:
1. External packages
2. Internal modules (absolute paths)
3. Relative imports
4. Types (with `type` keyword)

### Exports
- Use named exports (not default)
- Export types separately with `export type`
- Keep public API minimal

### Dependencies
- Each module declares its dependencies explicitly
- No circular dependencies
- Shared code goes in `shared/` or `common/`

## Error Handling Pattern

```typescript
// Define domain errors in types.ts
class DomainError extends Error {
  constructor(
    message: string,
    public code: string,
    public context?: Record<string, unknown>
  ) {
    super(message);
    this.name = 'DomainError';
  }
}

// Use Result type for recoverable errors
type Result<T, E = Error> = 
  | { success: true; data: T }
  | { success: false; error: E };
```

## Configuration Pattern

```typescript
// config/index.ts
export const config = {
  database: loadDatabaseConfig(),
  api: loadApiConfig(),
  // ...
} as const;

// Type-safe config access
export type Config = typeof config;
```

## Testing Strategy

- One test file per module
- Test public interface, not internals
- Use descriptive test names: `should [action] when [condition]`
- Mock external dependencies only

## Long-Context Development

This structure enables efficient development across long conversations:

1. **Adding features**: Identify target module → Read only that module → Implement
2. **Fixing bugs**: Locate affected module → Read module + its tests → Fix
3. **Refactoring**: Understand interface → Modify internals freely

The modular structure means Claude only needs to load relevant files, not the entire project.

## Workflow

1. **New project**: Read `references/templates.md` → Initialize structure
2. **New feature**: Create module skeleton → Define types → Implement → Test
3. **Modification**: Identify module → Load minimal context → Change
4. **Review**: Check file sizes → Verify interface clarity → Ensure test coverage

## References

- `references/templates.md` - Complete project templates by type
- `references/naming.md` - Comprehensive naming conventions
- `references/patterns.md` - Common code patterns and examples

Comments 0

Latest | Hot

Please login before commenting.

No comments yet. Be the first one!

engineering-code

Directory Structure

SKILL.md

Report

Notice