{"id":"fe940b0f-f953-4ca4-83b5-f3e6c7f85ea7","shortId":"XaRYzx","kind":"skill","title":"coding-principles","tagline":"Language-agnostic coding principles for maintainability, readability, and quality. Use when implementing features, refactoring code, or reviewing code quality.","description":"# Language-Agnostic Coding Principles\n\n## Core Philosophy\n\n1. **Maintainability over Speed**: Prioritize long-term code health over initial development velocity\n2. **Simplicity First**: Choose the simplest solution that meets requirements (YAGNI principle)\n3. **Explicit over Implicit**: Make intentions clear through code structure and naming\n4. **Delete over Comment**: Remove unused code instead of commenting it out\n\n## Code Quality\n\n### Continuous Improvement\n- Refactor related code within each change set — address style, naming, or structure issues in the files being modified\n- Improve code structure incrementally\n- Keep the codebase lean and focused\n- Delete unused code immediately\n\n### Readability\n- Use meaningful, descriptive names drawn from the problem domain\n- Use full words in names; abbreviations are acceptable only when widely recognized in the domain\n- Use descriptive names; single-letter names are acceptable only for loop counters or well-known conventions (i, j, x, y)\n- Extract magic numbers and strings into named constants\n- Keep code self-documenting where possible\n\n## Function Design\n\n### Parameter Management\n- **Recommended**: 0-2 parameters per function\n- **For 3+ parameters**: Use objects, structs, or dictionaries to group related parameters\n- **Example** (conceptual):\n  ```\n  // Instead of: createUser(name, email, age, city, country)\n  // Use: createUser(userData)\n  ```\n\n### Single Responsibility\n- Each function should do one thing well\n- Keep functions small and focused (typically < 50 lines)\n- Extract complex logic into separate, well-named functions\n- Functions should have a single level of abstraction\n\n### Function Organization\n- Pure functions when possible (no side effects)\n- Separate data transformation from side effects\n- Use early returns to reduce nesting\n- Keep nesting to a maximum of 3 levels; use early returns or extracted functions to flatten deeper nesting\n\n## Error Handling\n\n### Error Management Principles\n- **Always handle errors**: Log with context or propagate explicitly\n- **Log appropriately**: Include context for debugging\n- **Protect sensitive data**: Mask or exclude passwords, tokens, PII from logs\n- **Fail fast**: Detect and report errors as early as possible\n\n### Error Propagation\n- Use language-appropriate error handling mechanisms\n- Propagate errors to appropriate handling levels\n- Provide meaningful error messages\n- Include error context when re-throwing\n\n## Dependency Management\n\n### Loose Coupling via Parameterized Dependencies\n- Inject external dependencies as parameters (constructor injection for classes, function parameters for procedural/functional code)\n- Depend on abstractions, not concrete implementations\n- Minimize inter-module dependencies\n- Facilitate testing through mockable dependencies\n\n## Reference Representativeness\n\n### Verifying References Before Adoption\nWhen adopting patterns, APIs, or dependencies from existing code:\n- **IF** referencing only 2-3 nearby files → **THEN** confirm the pattern is representative by checking usage across the repository before adopting\n- **IF** multiple approaches coexist in the repository → **THEN** identify the majority pattern and make a deliberate choice — selecting whichever is nearest is insufficient\n- **IF** adopting an external dependency (library, plugin, SDK) → **THEN** verify repository-wide usage distribution for the same dependency; if the appropriate version cannot be determined from repository state alone, escalate\n- **IF** following an existing pattern → **THEN** state the reason for following it when an alternative exists (e.g., consistency with surrounding code, avoiding breaking changes, pending coordinated update)\n\n### Principle\nNearby code is a starting point for investigation, not a sufficient basis for adoption. Verify that what you reference is representative of the repository's conventions and current best practices before using it as a model.\n\n## Performance Considerations\n\n### Optimization Approach\n- **Measure first**: Profile before optimizing\n- **Focus on algorithms**: Algorithmic complexity > micro-optimizations\n- **Use appropriate data structures**: Choose based on access patterns\n- **Resource management**: Handle memory, connections, and files properly\n\n### When to Optimize\n- After identifying actual bottlenecks through profiling\n- When performance issues are measurable\n- Optimize only after measurable bottlenecks are identified, not during initial development\n\n## Code Organization\n\n### Structural Principles\n- **Group related functionality**: Keep related code together\n- **Separate concerns**: Domain logic, data access, presentation\n- **Consistent naming**: Follow project conventions\n- **Module cohesion**: High cohesion within modules, low coupling between\n\n### File Organization\n- One primary responsibility per file\n- Logical grouping of related functions/classes\n- Clear folder structure reflecting architecture\n- Avoid \"god files\" (files > 500 lines)\n\n## Commenting Principles\n\n### When to Comment\n- **Document \"what\"**: Describe what the code does\n- **Explain \"why\"**: Clarify reasoning behind decisions\n- **Note limitations**: Document known constraints or edge cases\n- **API documentation**: Public interfaces need clear documentation\n\n### Comment Scope\n- Comment the \"what\" and \"why\"; the code itself communicates the \"how\"\n- Record historical context in version control commit messages, not in comments\n- Delete commented-out code (retrieve from git history when needed)\n- Write comments that add information beyond what the code states\n\n### Comment Quality\n- Write comments that remain accurate regardless of future code changes; avoid references to dates, versions, or temporary state\n- Update comments when changing code\n- Use proper grammar and formatting\n- Write for future maintainers\n\n## Refactoring Approach\n\n### Safe Refactoring\n- **Small steps**: Make one change at a time\n- **Maintain working state**: Keep tests passing\n- **Verify behavior**: Run tests after each change\n- **Incremental improvement**: Don't aim for perfection immediately\n\n### Refactoring Triggers\n- Code duplication (DRY principle)\n- Functions > 50 lines\n- Complex conditional logic\n- Unclear naming or structure\n\n## Testing Considerations\n\n### Testability\n- Write testable code from the start\n- Avoid hidden dependencies\n- Keep side effects explicit\n- Design for parameterized dependencies\n\n### Test-Driven Development\n- Write tests before implementation when appropriate\n- Keep tests simple and focused\n- Test behavior, not implementation\n- Maintain test quality equal to production code\n\n## Security Principles\n\n### Secure Defaults\n- Store credentials and secrets through environment variables or dedicated secret managers\n- Use parameterized queries (prepared statements) for all database access\n- Use established cryptographic libraries provided by the language or framework\n- Generate security-critical values (tokens, IDs, nonces) with cryptographically secure random generators\n- Encrypt sensitive data at rest and in transit using standard protocols\n\n### Input and Output Boundaries\n- Validate all external input at system entry points for expected format, type, and length\n- Encode output appropriately for its rendering context (HTML, SQL, shell, URL)\n- Return only information necessary for the caller in error responses; log detailed diagnostics server-side\n\n### Access Control\n- Apply authentication to all entry points that handle user data or trigger state changes\n- Verify authorization for each resource access, not only at the entry point\n- Grant only the permissions required for the operation (files, database connections, API scopes)\n\n### Knowledge Cutoff Supplement (2026-03)\n- OWASP Top 10:2025 shifted from symptoms to root causes; added \"Software Supply Chain Failures\" (A03) and \"Mishandling of Exceptional Conditions\" (A10)\n- Recent research indicates AI-generated code shows elevated rates of access control gaps — treat authentication and authorization as high-priority review targets\n- OpenSSF published \"Security-Focused Guide for AI Code Assistant Instructions\" — recommends language-specific, actionable constraints over generic advice\n- For detailed detection patterns, see `references/security-checks.md`\n\n## Documentation\n\n### Code Documentation\n- Document public APIs and interfaces\n- Include usage examples for complex functionality\n- Maintain README files for modules\n- Update documentation in the same commit that changes the corresponding behavior\n\n### Architecture Documentation\n- Document high-level design decisions\n- Explain integration points\n- Clarify data flows and boundaries\n- Record trade-offs and alternatives considered\n\n## Version Control Practices\n\n### Commit Practices\n- Make atomic, focused commits\n- Write clear, descriptive commit messages\n- Commit working code (passes tests)\n- Commit only production-ready code; store secrets in environment variables or secret managers\n\n### Code Review Readiness\n- Self-review before requesting review\n- Keep changes focused and reviewable\n- Provide context in pull request descriptions\n- Respond to feedback constructively\n\n## Language-Specific Adaptations\n\nWhile these principles are language-agnostic, adapt them to your specific programming language:\n\n- **Static typing**: Use strong types when available\n- **Dynamic typing**: Add runtime validation\n- **OOP languages**: Apply SOLID principles\n- **Functional languages**: Prefer pure functions and immutability\n- **Concurrency**: Follow language-specific patterns for thread safety","tags":["coding","principles","claude","code","workflows","shinpr","agent-skills","agentic-ai","ai-agents","automation","claude-code","claude-code-plugin"],"capabilities":["skill","source-shinpr","skill-coding-principles","topic-agent-skills","topic-agentic-ai","topic-ai-agents","topic-automation","topic-claude-code","topic-claude-code-plugin","topic-code-quality","topic-developer-tools","topic-development-workflow","topic-llm-orchestration","topic-productivity","topic-prompt-engineering"],"categories":["claude-code-workflows"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/shinpr/claude-code-workflows/coding-principles","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add shinpr/claude-code-workflows","source_repo":"https://github.com/shinpr/claude-code-workflows","install_from":"skills.sh"}},"qualityScore":"0.613","qualityRationale":"deterministic score 0.61 from registry signals: · indexed on github topic:agent-skills · 327 github stars · SKILL.md body (9,536 chars)","verified":false,"liveness":"unknown","lastLivenessCheck":null,"agentReviews":{"count":0,"score_avg":null,"cost_usd_avg":null,"success_rate":null,"latency_p50_ms":null,"narrative_summary":null,"summary_updated_at":null},"enrichmentModel":"deterministic:skill-github:v1","enrichmentVersion":1,"enrichedAt":"2026-05-02T18:53:51.512Z","embedding":null,"createdAt":"2026-04-18T22:03:01.535Z","updatedAt":"2026-05-02T18:53:51.512Z","lastSeenAt":"2026-05-02T18:53:51.512Z","tsv":"'-03':1014 '-2':185 '-3':410 '0':184 '1':31 '10':1017 '2':45,409 '2025':1018 '2026':1013 '3':57,190,275 '4':69 '50':229,811 '500':657 'a03':1030 'a10':1036 'abbrevi':132 'abstract':247,377 'accept':134,150 'access':569,620,889,969,990,1048 'accur':743 'across':422 'action':1076 'actual':584 'ad':1025 'adapt':1200,1208 'add':730,1224 'address':92 'adopt':396,398,426,451,522 'advic':1080 'age':208 'agnost':6,26,1207 'ai':1041,1068 'ai-gener':1040 'aim':800 'algorithm':556,557 'alon':479 'altern':495,1138 'alway':292 'api':400,685,1008,1092 'appli':971,1229 'approach':429,548,772 'appropri':302,333,340,471,563,849,944 'architectur':652,1117 'assist':1070 'atom':1146 'authent':972,1052 'author':986,1054 'avail':1221 'avoid':502,653,749,829 'base':567 'basi':520 'behavior':790,856,1116 'behind':675 'best':537 'beyond':732 'bottleneck':585,597 'boundari':927,1132 'break':503 'caller':959 'cannot':473 'case':684 'caus':1024 'chain':1028 'chang':90,504,748,760,779,795,984,1113,1183 'check':420 'choic':443 'choos':48,566 'citi':209 'clarifi':673,1128 'class':369 'clear':63,648,690,1150 'code':2,7,19,22,27,39,65,75,81,87,104,115,173,374,405,501,510,604,613,669,700,720,735,747,761,806,825,865,1043,1069,1088,1156,1164,1173 'codebas':109 'coding-principl':1 'coexist':430 'cohes':628,630 'comment':72,78,659,663,692,694,715,718,728,737,740,758 'commented-out':717 'commit':711,1111,1143,1148,1152,1154,1159 'communic':702 'complex':232,558,813,1099 'conceptu':202 'concern':616 'concret':379 'concurr':1239 'condit':814,1035 'confirm':414 'connect':575,1007 'consid':1139 'consider':546,821 'consist':498,622 'constant':171 'constraint':681,1077 'construct':1196 'constructor':366 'context':297,304,349,707,948,1188 'continu':83 'control':710,970,1049,1141 'convent':159,534,626 'coordin':506 'core':29 'correspond':1115 'counter':154 'countri':210 'coupl':357,634 'createus':205,212 'credenti':871 'critic':903 'cryptograph':892,909 'current':536 'cutoff':1011 'data':258,309,564,619,915,980,1129 'databas':888,1006 'date':752 'debug':306 'decis':676,1124 'dedic':878 'deeper':285 'default':869 'delet':70,113,716 'deliber':442 'depend':354,360,363,375,385,390,402,454,468,831,839 'describ':666 'descript':120,143,1151,1192 'design':180,836,1123 'detail':964,1082 'detect':320,1083 'determin':475 'develop':43,603,843 'diagnost':965 'dictionari':196 'distribut':464 'document':176,664,679,686,691,1087,1089,1090,1107,1118,1119 'domain':126,141,617 'drawn':122 'dri':808 'driven':842 'duplic':807 'dynam':1222 'e.g':497 'earli':264,278,325 'edg':683 'effect':256,262,834 'elev':1045 'email':207 'encod':942 'encrypt':913 'entri':934,975,995 'environ':875,1168 'equal':862 'error':287,289,294,323,328,334,338,345,348,961 'escal':480 'establish':891 'exampl':201,1097 'except':1034 'exclud':312 'exist':404,484,496 'expect':937 'explain':671,1125 'explicit':58,300,835 'extern':362,453,930 'extract':164,231,281 'facilit':386 'fail':318 'failur':1029 'fast':319 'featur':17 'feedback':1195 'file':100,412,577,636,642,655,656,1005,1103 'first':47,550 'flatten':284 'flow':1130 'focus':112,227,554,854,1065,1147,1184 'folder':649 'follow':482,491,624,1240 'format':766,938 'framework':899 'full':128 'function':179,188,217,224,239,240,248,251,282,370,610,810,1100,1232,1236 'functions/classes':647 'futur':746,769 'gap':1050 'generat':900,912,1042 'generic':1079 'git':723 'god':654 'grammar':764 'grant':997 'group':198,608,644 'guid':1066 'handl':288,293,335,341,573,978 'health':40 'hidden':830 'high':629,1057,1121 'high-level':1120 'high-prior':1056 'histor':706 'histori':724 'html':949 'id':906 'identifi':435,583,599 'immedi':116,803 'immut':1238 'implement':16,380,847,858 'implicit':60 'improv':84,103,797 'includ':303,347,1095 'increment':106,796 'indic':1039 'inform':731,955 'initi':42,602 'inject':361,367 'input':924,931 'instead':76,203 'instruct':1071 'insuffici':449 'integr':1126 'intent':62 'inter':383 'inter-modul':382 'interfac':688,1094 'investig':516 'issu':97,590 'j':161 'keep':107,172,223,269,611,786,832,850,1182 'knowledg':1010 'known':158,680 'languag':5,25,332,897,1074,1198,1206,1214,1228,1233,1242 'language-agnost':4,24,1205 'language-appropri':331 'language-specif':1073,1197,1241 'lean':110 'length':941 'letter':147 'level':245,276,342,1122 'librari':455,893 'limit':678 'line':230,658,812 'log':295,301,317,963 'logic':233,618,643,815 'long':37 'long-term':36 'loop':153 'loos':356 'low':633 'magic':165 'maintain':10,32,770,783,859,1101 'major':437 'make':61,440,777,1145 'manag':182,290,355,572,880,1172 'mask':310 'maximum':273 'meaning':119,344 'measur':549,592,596 'mechan':336 'meet':53 'memori':574 'messag':346,712,1153 'micro':560 'micro-optim':559 'minim':381 'mishandl':1032 'mockabl':389 'model':544 'modifi':102 'modul':384,627,632,1105 'multipl':428 'name':68,94,121,131,144,148,170,206,238,623,817 'nearbi':411,509 'nearest':447 'necessari':956 'need':689,726 'nest':268,270,286 'nonc':907 'note':677 'number':166 'object':193 'off':1136 'one':220,638,778 'oop':1227 'openssf':1061 'oper':1004 'optim':547,553,561,581,593 'organ':249,605,637 'output':926,943 'owasp':1015 'paramet':181,186,191,200,365,371 'parameter':359,838,882 'pass':788,1157 'password':313 'pattern':399,416,438,485,570,1084,1244 'pend':505 'per':187,641 'perfect':802 'perform':545,589 'permiss':1000 'philosophi':30 'pii':315 'plugin':456 'point':514,935,976,996,1127 'possibl':178,253,327 'practic':538,1142,1144 'prefer':1234 'prepar':884 'present':621 'primari':639 'principl':3,8,28,56,291,508,607,660,809,867,1203,1231 'priorit':35 'prioriti':1058 'problem':125 'procedural/functional':373 'product':864,1162 'production-readi':1161 'profil':551,587 'program':1213 'project':625 'propag':299,329,337 'proper':578,763 'protect':307 'protocol':923 'provid':343,894,1187 'public':687,1091 'publish':1062 'pull':1190 'pure':250,1235 'qualiti':13,23,82,738,861 'queri':883 'random':911 'rate':1046 're':352 're-throw':351 'readabl':11,117 'readi':1163,1175 'readm':1102 'reason':489,674 'recent':1037 'recogn':138 'recommend':183,1072 'record':705,1133 'reduc':267 'refactor':18,85,771,774,804 'refer':391,394,527,750 'referenc':407 'references/security-checks.md':1086 'reflect':651 'regardless':744 'relat':86,199,609,612,646 'remain':742 'remov':73 'render':947 'report':322 'repositori':424,433,461,477,532 'repository-wid':460 'repres':392,418,529 'request':1180,1191 'requir':54,1001 'research':1038 'resourc':571,989 'respond':1193 'respons':215,640,962 'rest':917 'retriev':721 'return':265,279,953 'review':21,1059,1174,1178,1181,1186 'root':1023 'run':791 'runtim':1225 'safe':773 'safeti':1247 'scope':693,1009 'sdk':457 'secret':873,879,1166,1171 'secur':866,868,902,910,1064 'security-crit':901 'security-focus':1063 'see':1085 'select':444 'self':175,1177 'self-docu':174 'self-review':1176 'sensit':308,914 'separ':235,257,615 'server':967 'server-sid':966 'set':91 'shell':951 'shift':1019 'show':1044 'side':255,261,833,968 'simpl':852 'simplest':50 'simplic':46 'singl':146,214,244 'single-lett':145 'skill' 'skill-coding-principles' 'small':225,775 'softwar':1026 'solid':1230 'solut':51 'source-shinpr' 'specif':1075,1199,1212,1243 'speed':34 'sql':950 'standard':922 'start':513,828 'state':478,487,736,756,785,983 'statement':885 'static':1215 'step':776 'store':870,1165 'string':168 'strong':1218 'struct':194 'structur':66,96,105,565,606,650,819 'style':93 'suffici':519 'supplement':1012 'suppli':1027 'surround':500 'symptom':1021 'system':933 'target':1060 'temporari':755 'term':38 'test':387,787,792,820,841,845,851,855,860,1158 'test-driven':840 'testabl':822,824 'thing':221 'thread':1246 'throw':353 'time':782 'togeth':614 'token':314,905 'top':1016 'topic-agent-skills' 'topic-agentic-ai' 'topic-ai-agents' 'topic-automation' 'topic-claude-code' 'topic-claude-code-plugin' 'topic-code-quality' 'topic-developer-tools' 'topic-development-workflow' 'topic-llm-orchestration' 'topic-productivity' 'topic-prompt-engineering' 'trade':1135 'trade-off':1134 'transform':259 'transit':920 'treat':1051 'trigger':805,982 'type':939,1216,1219,1223 'typic':228 'unclear':816 'unus':74,114 'updat':507,757,1106 'url':952 'usag':421,463,1096 'use':14,118,127,142,192,211,263,277,330,540,562,762,881,890,921,1217 'user':979 'userdata':213 'valid':928,1226 'valu':904 'variabl':876,1169 'veloc':44 'verifi':393,459,523,789,985 'version':472,709,753,1140 'via':358 'well':157,222,237 'well-known':156 'well-nam':236 'whichev':445 'wide':137,462 'within':88,631 'word':129 'work':784,1155 'write':727,739,767,823,844,1149 'x':162 'y':163 'yagni':55","prices":[{"id":"6cec0ac9-7fd5-438e-a9ad-c22751a540ad","listingId":"fe940b0f-f953-4ca4-83b5-f3e6c7f85ea7","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"shinpr","category":"claude-code-workflows","install_from":"skills.sh"},"createdAt":"2026-04-18T22:03:01.535Z"}],"sources":[{"listingId":"fe940b0f-f953-4ca4-83b5-f3e6c7f85ea7","source":"github","sourceId":"shinpr/claude-code-workflows/coding-principles","sourceUrl":"https://github.com/shinpr/claude-code-workflows/tree/main/skills/coding-principles","isPrimary":false,"firstSeenAt":"2026-04-18T22:03:01.535Z","lastSeenAt":"2026-05-02T18:53:51.512Z"}],"details":{"listingId":"fe940b0f-f953-4ca4-83b5-f3e6c7f85ea7","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"shinpr","slug":"coding-principles","github":{"repo":"shinpr/claude-code-workflows","stars":327,"topics":["agent-skills","agentic-ai","ai-agents","automation","claude-code","claude-code-plugin","code-quality","developer-tools","development-workflow","llm-orchestration","productivity","prompt-engineering","skills"],"license":"mit","html_url":"https://github.com/shinpr/claude-code-workflows","pushed_at":"2026-05-02T15:39:17Z","description":"Production-ready development workflows for Claude Code, powered by specialized AI agents.","skill_md_sha":"001ccdba5502ea29662c7ca552bb2da5d6ea2529","skill_md_path":"skills/coding-principles/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/shinpr/claude-code-workflows/tree/main/skills/coding-principles"},"layout":"multi","source":"github","category":"claude-code-workflows","frontmatter":{"name":"coding-principles","description":"Language-agnostic coding principles for maintainability, readability, and quality. Use when implementing features, refactoring code, or reviewing code quality."},"skills_sh_url":"https://skills.sh/shinpr/claude-code-workflows/coding-principles"},"updatedAt":"2026-05-02T18:53:51.512Z"}}