musubix-best-practices
Guide for applying MUSUBIX's 17 learned best practices. Use this when asked about coding patterns, design patterns, or testing patterns that MUSUBIX recommends.
When & Why to Use This Skill
This Claude skill serves as a comprehensive guide for implementing 17 industry-proven best practices derived from extensive virtual project experience. It provides actionable patterns for coding, system design, and testing—such as Result types for robust error handling, DTOs for data integrity, and async repository patterns—to help developers build high-quality, maintainable, and scalable software architectures.
Use Cases
- Refactoring legacy code to use Input DTOs and Value Objects, reducing parameter complexity and improving type safety.
- Designing robust domain logic by implementing explicit status transition maps and optimistic locking to handle concurrent data updates.
- Establishing a scalable service layer using Dependency Injection and asynchronous Repository patterns to facilitate future database migrations.
- Improving API reliability by replacing exception-throwing logic with functional Result types for predictable error handling.
- Standardizing testing workflows with automated counter resets and specific patterns for verifying complex state transitions and edge cases.
| name | musubix-best-practices |
|---|---|
| description | Guide for applying MUSUBIX's 17 learned best practices. Use this when asked about coding patterns, design patterns, or testing patterns that MUSUBIX recommends. |
| license | MIT |
MUSUBIX Best Practices Skill
This skill guides you through applying the 17 best practices learned from MUSUBIX virtual projects.
Overview
MUSUBIX has learned these best practices from implementing 14+ virtual projects. Apply them consistently for high-quality code.
Code Patterns (5)
BP-CODE-001: Entity Input DTO
Use Input DTO objects for entity creation instead of multiple parameters.
// ✅ Recommended: Input DTO
interface CreatePetInput {
name: string;
species: string;
ownerId: string;
}
function createPet(input: CreatePetInput): Pet {
return new Pet(input);
}
// ❌ Avoid: Multiple parameters
function createPet(name: string, species: string, ownerId: string): Pet {
// Hard to extend, easy to mix up parameter order
}
BP-CODE-002: Date-based ID Format
Generate IDs with PREFIX-YYYYMMDD-NNN format for sortability.
// ✅ Recommended: Date-based ID
const id = `PET-20260104-001`; // Sortable, traceable
// ❌ Avoid: UUID only
const id = crypto.randomUUID(); // Not human-readable
BP-CODE-003: Value Objects
Use Value Objects for domain concepts.
// ✅ Recommended: Value Object
interface Price {
readonly amount: number;
readonly currency: 'JPY';
}
// ❌ Avoid: Primitive types
const price: number = 1000; // No currency context
BP-CODE-004: Function-based Value Objects
Use interface + factory function instead of classes for Value Objects.
// ✅ Recommended: Interface + Factory Function
interface Price {
readonly amount: number;
readonly currency: 'JPY';
}
function createPrice(amount: number): Result<Price, ValidationError> {
if (amount < 100 || amount > 1_000_000) {
return err(new ValidationError('Price must be between 100 and 1,000,000 JPY'));
}
return ok({ amount, currency: 'JPY' });
}
// ❌ Avoid: Class-based (doesn't work well with TypeScript structural typing)
class Price {
private constructor(readonly amount: number) {}
static create(amount: number): Price { ... }
}
BP-CODE-005: Result Type
Use Result<T, E> for operations that can fail.
// ✅ Recommended: Result type
type Result<T, E> = { ok: true; value: T } | { ok: false; error: E };
function divide(a: number, b: number): Result<number, Error> {
if (b === 0) return { ok: false, error: new Error('Division by zero') };
return { ok: true, value: a / b };
}
// ❌ Avoid: Throwing exceptions for expected errors
function divide(a: number, b: number): number {
if (b === 0) throw new Error('Division by zero');
return a / b;
}
Design Patterns (7)
BP-DESIGN-001: Status Transition Map
Define valid status transitions in a Map.
// ✅ Recommended: Transition map
const validTransitions: Record<Status, Status[]> = {
draft: ['active', 'cancelled'],
active: ['completed', 'cancelled'],
completed: [],
cancelled: [],
};
function canTransition(from: Status, to: Status): boolean {
return validTransitions[from].includes(to);
}
BP-DESIGN-002: Repository Async Pattern
Make repositories async for future DB migration.
// ✅ Recommended: Async repository
interface PetRepository {
findById(id: PetId): Promise<Pet | null>;
save(pet: Pet): Promise<void>;
}
// ❌ Avoid: Sync repository (hard to migrate later)
interface PetRepository {
findById(id: PetId): Pet | null;
}
BP-DESIGN-003: Service Layer with DI
Use dependency injection for services.
// ✅ Recommended: Constructor DI
class PetService {
constructor(
private readonly petRepository: PetRepository,
private readonly auditService: AuditService
) {}
}
BP-DESIGN-004: Optimistic Locking
Use version field for concurrent edit detection.
// ✅ Recommended: Version field
interface Entity {
id: string;
version: number;
updatedAt: Date;
}
function update(entity: Entity, currentVersion: number): Result<Entity, ConcurrencyError> {
if (entity.version !== currentVersion) {
return err(new ConcurrencyError('Entity was modified'));
}
return ok({ ...entity, version: entity.version + 1 });
}
BP-DESIGN-005: AuditService
Record data changes in audit logs.
// ✅ Recommended: Audit logging
interface AuditEntry {
id: string;
entityType: string;
entityId: string;
action: 'CREATE' | 'UPDATE' | 'DELETE';
changes: object;
userId: string;
timestamp: Date;
}
BP-DESIGN-006: Entity Counter Reset
Provide reset functions for test isolation.
// ✅ Recommended: Resettable counter
let petCounter = 0;
export function generatePetId(): string {
return `PET-${Date.now()}-${++petCounter}`;
}
export function resetPetCounter(): void {
petCounter = 0; // For tests
}
BP-DESIGN-007: Expiry Time Logic
Use expiresAt field for time-limited entities.
// ✅ Recommended: Explicit expiry
interface Reservation {
id: string;
createdAt: Date;
expiresAt: Date; // Explicit expiry time
}
function isExpired(reservation: Reservation): boolean {
return new Date() > reservation.expiresAt;
}
Test Patterns (5)
BP-TEST-001: Test Counter Reset
Reset ID counters in beforeEach.
beforeEach(() => {
resetPetCounter();
resetReservationCounter();
});
BP-TEST-002: Verify API Before Test
Check method signatures before writing tests.
BP-TEST-003: Vitest ESM Configuration
Use proper ESM setup for Vitest.
// vitest.config.ts
export default defineConfig({
test: {
globals: true,
environment: 'node',
},
});
BP-TEST-004: Result Type Test Pattern
Test both success and error cases.
it('should succeed with valid input', () => {
const result = createPrice(1000);
expect(result.isOk()).toBe(true);
});
it('should fail with invalid input', () => {
const result = createPrice(-1);
expect(result.isErr()).toBe(true);
});
BP-TEST-005: Status Transition Testing
Test all valid and invalid transitions.
describe('status transitions', () => {
it.each([
['draft', 'active', true],
['draft', 'completed', false],
['active', 'completed', true],
])('%s -> %s should be %s', (from, to, valid) => {
expect(canTransition(from, to)).toBe(valid);
});
});
CLI Commands
# Show all best practices
npx musubix learn best-practices
# Filter by category
npx musubix learn best-practices --category code
npx musubix learn best-practices --category design
npx musubix learn best-practices --category test
# High confidence only
npx musubix learn best-practices --high-confidence
Related Skills
musubix-code-generation- Apply patterns in codemusubix-test-generation- Apply test patternsmusubix-sdd-workflow- Full workflow with patterns