{"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. **Minimum Surface for Required Coverage**: When introducing maintenance-surface-bearing elements (persistent state, public-contract or cross-boundary fields/props, behavioral modes/flags/variants, reusable abstractions, or component splits), select the smallest design surface that covers the current user-visible requirements and accepted technical constraints (audit, data integrity, compatibility, security, performance, accessibility). Adoption is justified by naming a current requirement or constraint that smaller alternatives fail to cover; value-based arguments serve as tiebreakers. Distinct from YAGNI (time-axis judgment of present vs. future need), this principle governs surface-area minimization at a fixed coverage point.\n4. **Explicit over Implicit**: Make intentions clear through code structure and naming\n5. **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.629","qualityRationale":"deterministic score 0.63 from registry signals: · indexed on github topic:agent-skills · 358 github stars · SKILL.md body (10,277 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-18T18:54:29.437Z","embedding":null,"createdAt":"2026-04-18T22:03:01.535Z","updatedAt":"2026-05-18T18:54:29.437Z","lastSeenAt":"2026-05-18T18:54:29.437Z","tsv":"'-03':1115 '-2':286 '-3':511 '0':285 '1':31 '10':1118 '2':45,510 '2025':1119 '2026':1114 '3':57,291,376 '4':158 '5':170 '50':330,912 '500':758 'a03':1131 'a10':1137 'abbrevi':233 'abstract':83,348,478 'accept':101,235,251 'access':110,670,721,990,1070,1091,1149 'accur':844 'across':523 'action':1177 'actual':685 'ad':1126 'adapt':1301,1309 'add':831,1325 'address':193 'adopt':111,497,499,527,552,623 'advic':1181 'age':309 'agnost':6,26,1308 'ai':1142,1169 'ai-gener':1141 'aim':901 'algorithm':657,658 'alon':580 'altern':123,596,1239 'alway':393 'api':501,786,1109,1193 'appli':1072,1330 'approach':530,649,873 'appropri':403,434,441,572,664,950,1045 'architectur':753,1218 'area':151 'argument':130 'assist':1171 'atom':1247 'audit':104 'authent':1073,1153 'author':1087,1155 'avail':1322 'avoid':603,754,850,930 'axi':139 'base':129,668 'basi':621 'bear':68 'behavior':80,891,957,1217 'behind':776 'best':638 'beyond':833 'bottleneck':686,698 'boundari':78,1028,1233 'break':604 'caller':1060 'cannot':574 'case':785 'caus':1125 'chain':1129 'chang':191,605,849,861,880,896,1085,1214,1284 'check':521 'choic':544 'choos':48,667 'citi':310 'clarifi':774,1229 'class':470 'clear':164,749,791,1251 'code':2,7,19,22,27,39,166,176,182,188,205,216,274,475,506,602,611,705,714,770,801,821,836,848,862,907,926,966,1144,1170,1189,1257,1265,1274 'codebas':210 'coding-principl':1 'coexist':531 'cohes':729,731 'comment':173,179,760,764,793,795,816,819,829,838,841,859 'commented-out':818 'commit':812,1212,1244,1249,1253,1255,1260 'communic':803 'compat':107 'complex':333,659,914,1200 'compon':85 'conceptu':303 'concern':717 'concret':480 'concurr':1340 'condit':915,1136 'confirm':515 'connect':676,1108 'consid':1240 'consider':647,922 'consist':599,723 'constant':272 'constraint':103,120,782,1178 'construct':1297 'constructor':467 'context':398,405,450,808,1049,1289 'continu':184 'contract':74 'control':811,1071,1150,1242 'convent':260,635,727 'coordin':607 'core':29 'correspond':1216 'counter':255 'countri':311 'coupl':458,735 'cover':93,126 'coverag':62,156 'createus':306,313 'credenti':972 'critic':1004 'cross':77 'cross-boundari':76 'cryptograph':993,1010 'current':95,117,637 'cutoff':1112 'data':105,359,410,665,720,1016,1081,1230 'databas':989,1107 'date':853 'debug':407 'decis':777,1225 'dedic':979 'deeper':386 'default':970 'delet':171,214,817 'deliber':543 'depend':455,461,464,476,486,491,503,555,569,932,940 'describ':767 'descript':221,244,1252,1293 'design':90,281,937,1224 'detail':1065,1183 'detect':421,1184 'determin':576 'develop':43,704,944 'diagnost':1066 'dictionari':297 'distinct':134 'distribut':565 'document':277,765,780,787,792,1188,1190,1191,1208,1219,1220 'domain':227,242,718 'drawn':223 'dri':909 'driven':943 'duplic':908 'dynam':1323 'e.g':598 'earli':365,379,426 'edg':784 'effect':357,363,935 'element':69 'elev':1146 'email':308 'encod':1043 'encrypt':1014 'entri':1035,1076,1096 'environ':976,1269 'equal':963 'error':388,390,395,424,429,435,439,446,449,1062 'escal':581 'establish':992 'exampl':302,1198 'except':1135 'exclud':413 'exist':505,585,597 'expect':1038 'explain':772,1226 'explicit':159,401,936 'extern':463,554,1031 'extract':265,332,382 'facilit':487 'fail':124,419 'failur':1130 'fast':420 'featur':17 'feedback':1296 'fields/props':79 'file':201,513,678,737,743,756,757,1106,1204 'first':47,651 'fix':155 'flatten':385 'flow':1231 'focus':213,328,655,955,1166,1248,1285 'folder':750 'follow':583,592,725,1341 'format':867,1039 'framework':1000 'full':229 'function':280,289,318,325,340,341,349,352,383,471,711,911,1201,1333,1337 'functions/classes':748 'futur':144,847,870 'gap':1151 'generat':1001,1013,1143 'generic':1180 'git':824 'god':755 'govern':148 'grammar':865 'grant':1098 'group':299,709,745 'guid':1167 'handl':389,394,436,442,674,1079 'health':40 'hidden':931 'high':730,1158,1222 'high-level':1221 'high-prior':1157 'histor':807 'histori':825 'html':1050 'id':1007 'identifi':536,684,700 'immedi':217,904 'immut':1339 'implement':16,481,948,959 'implicit':161 'improv':185,204,898 'includ':404,448,1196 'increment':207,897 'indic':1140 'inform':832,1056 'initi':42,703 'inject':462,468 'input':1025,1032 'instead':177,304 'instruct':1172 'insuffici':550 'integr':106,1227 'intent':163 'inter':484 'inter-modul':483 'interfac':789,1195 'introduc':64 'investig':617 'issu':198,691 'j':262 'judgment':140 'justifi':113 'keep':208,273,324,370,712,887,933,951,1283 'knowledg':1111 'known':259,781 'languag':5,25,433,998,1175,1299,1307,1315,1329,1334,1343 'language-agnost':4,24,1306 'language-appropri':432 'language-specif':1174,1298,1342 'lean':211 'length':1042 'letter':248 'level':346,377,443,1223 'librari':556,994 'limit':779 'line':331,759,913 'log':396,402,418,1064 'logic':334,719,744,916 'long':37 'long-term':36 'loop':254 'loos':457 'low':734 'magic':266 'maintain':10,32,871,884,960,1202 'mainten':66 'maintenance-surface-bear':65 'major':538 'make':162,541,878,1246 'manag':283,391,456,673,981,1273 'mask':411 'maximum':374 'meaning':220,445 'measur':650,693,697 'mechan':437 'meet':53 'memori':675 'messag':447,813,1254 'micro':661 'micro-optim':660 'minim':152,482 'minimum':58 'mishandl':1133 'mockabl':490 'model':645 'modes/flags/variants':81 'modifi':203 'modul':485,728,733,1206 'multipl':529 'name':115,169,195,222,232,245,249,271,307,339,724,918 'nearbi':512,610 'nearest':548 'necessari':1057 'need':145,790,827 'nest':369,371,387 'nonc':1008 'note':778 'number':267 'object':294 'off':1237 'one':321,739,879 'oop':1328 'openssf':1162 'oper':1105 'optim':648,654,662,682,694 'organ':350,706,738 'output':1027,1044 'owasp':1116 'paramet':282,287,292,301,466,472 'parameter':460,939,983 'pass':889,1258 'password':414 'pattern':500,517,539,586,671,1185,1345 'pend':606 'per':288,742 'perfect':903 'perform':109,646,690 'permiss':1101 'persist':70 'philosophi':30 'pii':416 'plugin':557 'point':157,615,1036,1077,1097,1228 'possibl':279,354,428 'practic':639,1243,1245 'prefer':1335 'prepar':985 'present':142,722 'primari':740 'principl':3,8,28,56,147,392,609,708,761,910,968,1304,1332 'priorit':35 'prioriti':1159 'problem':226 'procedural/functional':474 'product':965,1263 'production-readi':1262 'profil':652,688 'program':1314 'project':726 'propag':400,430,438 'proper':679,864 'protect':408 'protocol':1024 'provid':444,995,1288 'public':73,788,1192 'public-contract':72 'publish':1163 'pull':1291 'pure':351,1336 'qualiti':13,23,183,839,962 'queri':984 'random':1012 'rate':1147 're':453 're-throw':452 'readabl':11,218 'readi':1264,1276 'readm':1203 'reason':590,775 'recent':1138 'recogn':239 'recommend':284,1173 'record':806,1234 'reduc':368 'refactor':18,186,872,875,905 'refer':492,495,628,851 'referenc':508 'references/security-checks.md':1187 'reflect':752 'regardless':845 'relat':187,300,710,713,747 'remain':843 'remov':174 'render':1048 'report':423 'repositori':525,534,562,578,633 'repository-wid':561 'repres':493,519,630 'request':1281,1292 'requir':54,61,99,118,1102 'research':1139 'resourc':672,1090 'respond':1294 'respons':316,741,1063 'rest':1018 'retriev':822 'return':366,380,1054 'reusabl':82 'review':21,1160,1275,1279,1282,1287 'root':1124 'run':892 'runtim':1326 'safe':874 'safeti':1348 'scope':794,1110 'sdk':558 'secret':974,980,1267,1272 'secur':108,967,969,1003,1011,1165 'security-crit':1002 'security-focus':1164 'see':1186 'select':87,545 'self':276,1278 'self-docu':275 'self-review':1277 'sensit':409,1015 'separ':336,358,716 'serv':131 'server':1068 'server-sid':1067 'set':192 'shell':1052 'shift':1120 'show':1145 'side':356,362,934,1069 'simpl':953 'simplest':50 'simplic':46 'singl':247,315,345 'single-lett':246 'skill' 'skill-coding-principles' 'small':326,876 'smaller':122 'smallest':89 'softwar':1127 'solid':1331 'solut':51 'source-shinpr' 'specif':1176,1300,1313,1344 'speed':34 'split':86 'sql':1051 'standard':1023 'start':614,929 'state':71,579,588,837,857,886,1084 'statement':986 'static':1316 'step':877 'store':971,1266 'string':269 'strong':1319 'struct':295 'structur':167,197,206,666,707,751,920 'style':194 'suffici':620 'supplement':1113 'suppli':1128 'surfac':59,67,91,150 'surface-area':149 'surround':601 'symptom':1122 'system':1034 'target':1161 'technic':102 'temporari':856 'term':38 'test':488,888,893,921,942,946,952,956,961,1259 'test-driven':941 'testabl':923,925 'thing':322 'thread':1347 'throw':454 'tiebreak':133 'time':138,883 'time-axi':137 'togeth':715 'token':415,1006 'top':1117 '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':1236 'trade-off':1235 'transform':360 'transit':1021 'treat':1152 'trigger':906,1083 'type':1040,1317,1320,1324 'typic':329 'unclear':917 'unus':175,215 'updat':608,858,1207 'url':1053 'usag':522,564,1197 'use':14,219,228,243,293,312,364,378,431,641,663,863,982,991,1022,1318 'user':97,1080 'user-vis':96 'userdata':314 'valid':1029,1327 'valu':128,1005 'value-bas':127 'variabl':977,1270 'veloc':44 'verifi':494,560,624,890,1086 'version':573,810,854,1241 'via':459 'visibl':98 'vs':143 'well':258,323,338 'well-known':257 'well-nam':337 'whichev':546 'wide':238,563 'within':189,732 'word':230 'work':885,1256 'write':828,840,868,924,945,1250 'x':263 'y':264 'yagni':55,136","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-18T18:54:29.437Z"}],"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":358,"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-16T07:20:38Z","description":"Production-ready development workflows for Claude Code, powered by specialized AI agents.","skill_md_sha":"a1e95a92da598fea3c5f2102a4a0069fb07eb101","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-18T18:54:29.437Z"}}