# Shinpr Agentic Code Coding Rules

> Development Rules

- Skill: `tomevault-io/shinpr-agentic-code-coding-rules` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/shinpr-agentic-code-coding-rules`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/shinpr-agentic-code-coding-rules/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/shinpr-agentic-code-coding-rules

---


# Development Rules

## Language-Specific References

For language-specific rules, also read:
- **TypeScript**: [references/typescript.md](references/typescript.md)

## Basic Principles

✅ **Aggressive Refactoring**
- Continuously improve code structure and readability
- Make code changes in small, safe steps
- Prioritize maintainability over initial implementation speed

❌ **Unused "Just in Case" Code** - YAGNI principle
- Don't write code for hypothetical future requirements
- Delete unused functions, variables, and imports immediately
- Keep codebase lean and focused on current needs

## Comment Writing Rules

- **Function Description Focus**: Describe what the code "does", not how it works
- **No Historical Information**: Do not record development history in comments
- **Timeless**: Write only content that remains valid whenever read
- **Conciseness**: Keep explanations to necessary minimum
- **Explain "Why"**: Comments should explain reasoning, not implementation details

## Function Design

**Parameter Management**
- **0-2 parameters maximum**: Use structured data (object/struct/dict) for 3+ parameters
  ```
  ✅ Good: createUser({name, email, role})
  ❌ Avoid: createUser(name, email, role, department, startDate)
  ```
  *Note: Use your language's idiomatic approach for grouping parameters*

**Dependency Injection**
- **Inject external dependencies explicitly**: Ensure testability and modularity
- Pass dependencies as parameters (functions, constructors, or other language-appropriate mechanisms)
- Avoid global state, direct instantiation, or implicit dependencies
- Prefer interfaces/contracts over concrete implementations where applicable

## Error Handling

**Absolute Rule**: Error suppression prohibited. All errors must have log output and appropriate handling.

**Layer-Specific Error Handling**
- **Presentation Layer**: Convert errors to user-friendly messages, log excluding sensitive information
- **Business Layer**: Detect business rule violations, propagate domain-specific errors
- **Data Layer**: Convert technical errors to domain errors

**Structured Logging and Sensitive Information Protection**
Never include sensitive information in logs:
- Passwords, tokens, API keys, secrets
- Credit card numbers, personal identification numbers
- Any personally identifiable information (PII)

**Asynchronous Error Handling**
- Use appropriate error handling mechanisms for your language
- Always log and appropriately propagate errors
- Set up global error handlers where applicable

## Clean Code Principles

✅ **Recommended Practices**
- Delete unused code immediately
- Remove debug statements and temporary logging
- Use meaningful variable and function names
- Keep functions small and focused on single responsibility

❌ **Avoid These Practices**
- Commented-out code (use version control for history)
- Magic numbers without explanation
- Deep nesting (prefer early returns)
- Functions that do multiple unrelated things

## Refactoring Techniques

**Basic Policy**
- **Small Steps**: Maintain always-working state through gradual improvements
- **Safe Changes**: Minimize the scope of changes at once
- **Behavior Guarantee**: Ensure existing behavior remains unchanged while proceeding

**Implementation Procedure**
1. Understand Current State
2. Make Gradual Changes
3. Verify Behavior
4. Final Validation

**Priority Order**
1. Duplicate Code Removal
2. Large Function Division
3. Complex Conditional Branch Simplification
4. Architecture Improvement

## Performance Considerations

**General Principles**
- Measure before optimizing (avoid premature optimization)
- Focus on algorithmic complexity over micro-optimizations
- Consider memory usage, especially with large datasets
- Use appropriate data structures for the use case

**Resource Management**
- Properly close files, connections, and other resources
- Be mindful of memory leaks in long-running applications
- Use efficient algorithms for data processing

## Code Organization

**File Structure**
- Group related functionality together
- Separate concerns (business logic, data access, presentation)
- Use consistent naming conventions throughout the project
- Keep configuration separate from business logic

**Modularity**
- Write small, focused modules/functions
- Minimize dependencies between modules
- Use clear interfaces between components
- Follow single responsibility principle

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/shinpr) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-11 -->