{"id":"ab379109-c118-4685-8827-2627ba772b10","shortId":"GUdcRT","kind":"skill","title":"frontend-ai-guide","tagline":"Frontend-specific technical decision criteria, anti-patterns, debugging techniques, and quality check workflow. Use when making frontend technical decisions or performing quality assurance.","description":"# AI Developer Guide - Technical Decision Criteria and Anti-pattern Collection (Frontend)\n\n## Technical Anti-patterns (Red Flag Patterns)\n\nImmediately stop and reconsider design when detecting the following patterns:\n\n### Code Quality Anti-patterns\n1. **Writing similar code 3 or more times** - Violates Rule of Three\n2. **Multiple responsibilities mixed in a single component** - Violates Single Responsibility Principle (SRP)\n3. **Defining same content in multiple components** - Violates DRY principle\n4. **Making changes without checking dependencies** - Potential for unexpected impacts\n5. **Disabling code with comments** - Should use version control\n6. **Error suppression** - Hiding problems creates technical debt\n7. **Excessive use of type assertions (as)** - Abandoning type safety\n8. **Prop drilling through 3+ levels** - Should use Context API or state management\n9. **Massive components (300+ lines)** - Split into smaller components\n\n### Design Anti-patterns\n- **\"Make it work for now\" thinking** - Accumulation of technical debt\n- **Patchwork implementation** - Unplanned additions to existing components\n- **Optimistic implementation of uncertain technology** - Designing unknown elements assuming \"it'll probably work\"\n- **Symptomatic fixes** - Surface-level fixes that don't solve root causes\n- **Unplanned large-scale changes** - Lack of incremental approach\n\n## Fallback Design Principles\n\n### Core Principle: Fail-Fast\nDesign philosophy that prioritizes improving primary code reliability over fallback implementations.\n\n### Criteria for Fallback Implementation\n- **Fallback rule**: Implement fallbacks only when explicitly defined in Design Doc\n- **Layer Responsibilities**:\n  - Component Layer: Use Error Boundary for error handling\n  - Hook Layer: Implement decisions based on business requirements\n\n### Detection of Excessive Fallbacks\n- Require design review when writing the 3rd catch statement in the same feature\n- Verify Design Doc definition before implementing fallbacks\n- Properly log errors and make failures explicit\n\n## Rule of Three - Criteria for Code Duplication\n\nHow to handle duplicate code based on Martin Fowler's \"Refactoring\":\n\n| Duplication Count | Action | Reason |\n|-------------------|--------|--------|\n| 1st time | Inline implementation | Cannot predict future changes |\n| 2nd time | Consider future consolidation | Pattern beginning to emerge |\n| 3rd time | Implement commonalization | Pattern established |\n\n### Criteria for Commonalization\n\n**Cases for Commonalization**\n- Business logic duplication\n- Complex processing algorithms\n- Component patterns (form fields, cards, etc.)\n- Custom hooks\n- Validation rules\n\n**Cases to Avoid Commonalization**\n- Accidental matches (coincidentally same code)\n- Possibility of evolving in different directions\n- Significant readability decrease from commonalization\n- Simple helpers in test code\n\n### Implementation Example\n```typescript\n// Immediate commonalization on 1st duplication\nfunction UserEmailInput() { /* ... */ }\nfunction ContactEmailInput() { /* ... */ }\n\n// Commonalize on 3rd occurrence\nfunction EmailInput({ context }: { context: 'user' | 'contact' | 'admin' }) { /* ... */ }\n```\n\n## Common Failure Patterns and Avoidance Methods\n\n### Pattern 1: Error Fix Chain\n**Symptom**: Fixing one error causes new errors\n**Cause**: Surface-level fixes without understanding root cause\n**Avoidance**: Identify root cause with 5 Whys before fixing\n\n### Pattern 2: Abandoning Type Safety\n**Symptom**: Excessive use of any type or as\n**Cause**: Impulse to avoid type errors\n**Avoidance**: Handle safely with unknown type and type guards\n\n### Pattern 3: Implementation Without Sufficient Testing\n**Symptom**: Many bugs after implementation\n**Cause**: Ignoring Red-Green-Refactor process\n**Avoidance**: Always start with failing tests\n\n### Pattern 4: Ignoring Technical Uncertainty\n**Symptom**: Frequent unexpected errors when introducing new technology\n**Cause**: Assuming \"it should work according to official documentation\" without prior investigation\n**Avoidance**:\n- Record certainty evaluation at the beginning of task files\n  ```\n  Certainty: low (Reason: new experimental feature with limited production examples)\n  Exploratory implementation: true\n  Fallback: use established patterns\n  ```\n- For low certainty cases, create minimal verification code first\n\n### Pattern 5: Insufficient Existing Code Investigation\n**Symptom**: Duplicate implementations, architecture inconsistency, integration failures\n**Cause**: Insufficient understanding of existing code before implementation\n**Avoidance Methods**:\n- Before implementation, always search for similar functionality (using domain, responsibility, component patterns as keywords)\n- Similar functionality found → Use that implementation (do not create new implementation)\n- Similar functionality is technical debt → Create ADR improvement proposal before implementation\n- No similar functionality exists → Implement new functionality following existing design philosophy\n- Record all decisions and rationale in \"Existing Codebase Analysis\" section of Design Doc\n\n## Debugging Techniques\n\n### 1. Error Analysis Procedure\n1. Read error message (first line) accurately\n2. Focus on first and last of stack trace\n3. Identify first line where your code appears\n4. Check React DevTools for component hierarchy\n\n### 2. 5 Whys - Root Cause Analysis\n```\nSymptom: Component not rendering\nWhy1: Props are undefined → Why2: Parent component didn't pass props\nWhy3: Parent using old prop names → Why4: Component interface was updated\nWhy5: No update to parent after refactoring\nRoot cause: Incomplete refactoring, missing call-site updates\n```\n\n### 3. Minimal Reproduction Code\nTo isolate problems, attempt reproduction with minimal code:\n- Remove unrelated components\n- Replace API calls with mocks\n- Create minimal configuration that reproduces problem\n- Use React DevTools to inspect component tree\n\n### 4. Debug Log Output\n```typescript\nconsole.log('DEBUG:', {\n  context: 'user-form-submission',\n  props: { email, name },\n  state: currentState,\n  timestamp: new Date().toISOString()\n})\n```\n\n## Quality Check Workflow\n\nUse the appropriate run command based on the `packageManager` field in package.json.\n\n### Build Commands\n- `dev` - Development server\n- `build` - Production build\n- `preview` - Preview production build\n- `type-check` - Type check (no emit)\n\n### Quality Check Phases\n\n**Phase 1-3: Basic Checks**\n- `check` - Biome (lint + format)\n- `build` - TypeScript build\n\n**Phase 4-5: Tests and Final Confirmation**\n- `test` - Test execution\n- `test:coverage:fresh` - Coverage measurement (fresh cache)\n- `check:all` - Overall integrated check\n\n### Auxiliary Commands\n- `test:coverage` - Run tests with coverage\n- `test:safe` - Safe test execution (with auto cleanup)\n- `cleanup:processes` - Cleanup Vitest processes\n- `format` - Format fixes\n- `lint:fix` - Lint fixes\n- `open coverage/index.html` - Check coverage report\n\n### Troubleshooting\n- **Port in use error**: Run `cleanup:processes` script\n- **Cache issues**: Run `test:coverage:fresh` script\n- **Dependency errors**: Clean reinstall dependencies\n- **Vite preview not starting**: Check port 4173 availability\n\n## Situations Requiring Technical Decisions\n\n### Timing of Abstraction\n- Extract patterns after writing concrete implementation 3 times\n- Be conscious of YAGNI, implement only currently needed features\n- Prioritize current simplicity over future extensibility\n\n### Performance vs Readability\n- Prioritize readability unless React DevTools Profiler identifies a measurable bottleneck (e.g., render time exceeding 16ms, unnecessary re-renders)\n- Measure before optimizing with React DevTools Profiler\n- Document reason with comments when optimizing\n\n### Granularity of Component/Type Definitions\n- Overly detailed components/types reduce maintainability\n- Design components that appropriately express UI patterns\n- Use composition over inheritance\n\n## Implementation Completeness Assurance\n\n### Required Procedure for Impact Analysis\n\n**Completion Criteria**: Complete all 3 stages\n\n#### 1. Discovery\n```bash\nGrep -n \"ComponentName\\|hookName\" -o content\nGrep -n \"importedFunction\" -o content\nGrep -n \"propsType\\|StateType\" -o content\n```\n\n#### 2. Understanding\n**Mandatory**: Read all discovered files and include necessary parts in context:\n- Caller's purpose and context\n- Component hierarchy\n- Data flow: Props → State → Event handlers → Callbacks\n\n#### 3. Identification\nStructured impact report (mandatory):\n```\n## Impact Analysis\n### Direct Impact: ComponentA, ComponentB (with reasons)\n### Indirect Impact: FeatureX, PageY (with integration paths)\n### Processing Flow: Props → Render → Events → Callbacks\n```\n\n**Important**: Execute all 3 stages to completion\n\n### Unused Code Deletion Rule\n\nWhen unused code is detected → Will it be used?\n- Yes → Implement immediately (no deferral allowed)\n- No → Delete immediately (remains in Git history)\n\nTarget: Components, hooks, utilities, documentation, configuration files\n\n### Existing Code Deletion Decision Flow\n\n```\nIn use? No → Delete immediately (remains in Git history)\n       Yes → Working? No → Delete + Reimplement\n                     Yes → Fix\n```","tags":["frontend","guide","claude","code","workflows","shinpr","agent-skills","agentic-ai","ai-agents","automation","claude-code","claude-code-plugin"],"capabilities":["skill","source-shinpr","skill-frontend-ai-guide","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/frontend-ai-guide","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,224 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.647Z","embedding":null,"createdAt":"2026-04-18T22:03:03.081Z","updatedAt":"2026-05-02T18:53:51.647Z","lastSeenAt":"2026-05-02T18:53:51.647Z","tsv":"'-3':821 '-5':833 '1':64,418,645,649,820,1014 '16ms':962 '1st':318,394 '2':76,448,656,680,1034 '2nd':326 '3':68,89,140,476,665,728,928,1012,1061,1091 '300':152 '3rd':275,335,402 '4':99,500,673,761,832 '4173':913 '5':109,443,561,681 '6':118 '7':126 '8':136 '9':149 'abandon':133,449 'abstract':921 'accident':367 'accord':517 'accumul':168 'accur':655 'action':316 'addit':175 'admin':410 'adr':614 'ai':3,30 'algorithm':352 'allow':1113 'alway':494,585 'analysi':638,647,685,1007,1068 'anti':12,38,44,62,160 'anti-pattern':11,37,43,61,159 'api':145,744 'appear':672 'approach':212 'appropri':787,992 'architectur':569 'assert':131 'assum':187,513 'assur':29,1002 'attempt':735 'auto':867 'auxiliari':853 'avail':914 'avoid':365,415,438,463,466,493,524,581 'base':261,308,790 'bash':1016 'basic':822 'begin':332,530 'biom':825 'bottleneck':957 'boundari':253 'bug':483 'build':797,802,804,808,828,830 'busi':263,347 'cach':847,895 'call':725,745 'call-sit':724 'callback':1060,1087 'caller':1047 'cannot':322 'card':357 'case':344,363,554 'catch':276 'caus':203,426,429,437,441,460,486,512,573,684,720 'certainti':526,534,553 'chain':421 'chang':101,208,325 'check':18,103,674,783,811,813,817,823,824,848,852,883,911 'clean':904 'cleanup':868,869,871,892 'code':59,67,111,227,301,307,371,387,558,564,578,671,731,739,1096,1101,1129 'codebas':637 'coincident':369 'collect':40 'command':789,798,854 'comment':113,977 'common':338,343,346,366,382,392,400,411 'complet':1001,1008,1010,1094 'complex':350 'compon':83,95,151,157,178,249,353,593,678,687,696,708,742,759,990,1052,1122 'component/type':982 'componenta':1071 'componentb':1072 'componentnam':1019 'components/types':986 'composit':997 'concret':926 'configur':750,1126 'confirm':837 'conscious':931 'consid':328 'console.log':766 'consolid':330 'contact':409 'contactemailinput':399 'content':92,1022,1027,1033 'context':144,406,407,768,1046,1051 'control':117 'core':216 'count':315 'coverag':842,844,856,860,884,899 'coverage/index.html':882 'creat':123,555,605,613,748 'criteria':10,35,232,299,341,1009 'current':936,940 'currentst':777 'custom':359 'data':1054 'date':780 'debt':125,171,612 'debug':14,643,762,767 'decis':9,25,34,260,632,918,1131 'decreas':380 'deferr':1112 'defin':90,243 'definit':285,983 'delet':1097,1115,1130,1136,1145 'depend':104,902,906 'design':53,158,184,214,221,245,270,283,628,641,989 'detail':985 'detect':55,265,1103 'dev':799 'develop':31,800 'devtool':676,756,952,972 'didn':697 'differ':376 'direct':377,1069 'disabl':110 'discov':1039 'discoveri':1015 'doc':246,284,642 'document':520,974,1125 'domain':591 'dri':97 'drill':138 'duplic':302,306,314,349,395,567 'e.g':958 'element':186 'email':774 'emailinput':405 'emerg':334 'emit':815 'error':119,252,255,291,419,425,428,465,507,646,651,890,903 'establish':340,549 'etc':358 'evalu':527 'event':1058,1086 'evolv':374 'exampl':389,543 'exceed':961 'excess':127,267,453 'execut':840,865,1089 'exist':177,563,577,622,627,636,1128 'experiment':538 'explicit':242,295 'exploratori':544 'express':993 'extens':944 'extract':922 'fail':219,497 'fail-fast':218 'failur':294,412,572 'fallback':213,230,234,236,239,268,288,547 'fast':220 'featur':281,539,938 'featurex':1077 'field':356,794 'file':533,1040,1127 'final':836 'first':559,653,659,667 'fix':193,197,420,423,433,446,876,878,880,1148 'flag':47 'flow':1055,1083,1132 'focus':657 'follow':57,626 'form':355,771 'format':827,874,875 'found':599 'fowler':311 'frequent':505 'fresh':843,846,900 'frontend':2,6,23,41 'frontend-ai-guid':1 'frontend-specif':5 'function':396,398,404,589,598,609,621,625 'futur':324,329,943 'git':1119,1140 'granular':980 'green':490 'grep':1017,1023,1028 'guard':474 'guid':4,32 'handl':256,305,467 'handler':1059 'helper':384 'hide':121 'hierarchi':679,1053 'histori':1120,1141 'hook':257,360,1123 'hooknam':1020 'identif':1062 'identifi':439,666,954 'ignor':487,501 'immedi':49,391,1110,1116,1137 'impact':108,1006,1064,1067,1070,1076 'implement':173,180,231,235,238,259,287,321,337,388,477,485,545,568,580,584,602,607,618,623,927,934,1000,1109 'import':1088 'importedfunct':1025 'improv':225,615 'impuls':461 'includ':1042 'incomplet':721 'inconsist':570 'increment':211 'indirect':1075 'inherit':999 'inlin':320 'inspect':758 'insuffici':562,574 'integr':571,851,1080 'interfac':709 'introduc':509 'investig':523,565 'isol':733 'issu':896 'keyword':596 'lack':209 'larg':206 'large-scal':205 'last':661 'layer':247,250,258 'level':141,196,432 'limit':541 'line':153,654,668 'lint':826,877,879 'll':189 'log':290,763 'logic':348 'low':535,552 'maintain':988 'make':22,100,162,293 'manag':148 'mandatori':1036,1066 'mani':482 'martin':310 'massiv':150 'match':368 'measur':845,956,967 'messag':652 'method':416,582 'minim':556,729,738,749 'miss':723 'mix':79 'mock':747 'multipl':77,94 'n':1018,1024,1029 'name':706,775 'necessari':1043 'need':937 'new':427,510,537,606,624,779 'o':1021,1026,1032 'occurr':403 'offici':519 'old':704 'one':424 'open':881 'optim':969,979 'optimist':179 'output':764 'over':984 'overal':850 'package.json':796 'packagemanag':793 'pagey':1078 'parent':695,702,716 'part':1044 'pass':699 'patchwork':172 'path':1081 'pattern':13,39,45,48,58,63,161,331,339,354,413,417,447,475,499,550,560,594,923,995 'perform':27,945 'phase':818,819,831 'philosophi':222,629 'port':887,912 'possibl':372 'potenti':105 'predict':323 'preview':805,806,908 'primari':226 'principl':87,98,215,217 'prior':522 'priorit':224,939,948 'probabl':190 'problem':122,734,753 'procedur':648,1004 'process':351,492,870,873,893,1082 'product':542,803,807 'profil':953,973 'prop':137,691,700,705,773,1056,1084 'proper':289 'propos':616 'propstyp':1030 'purpos':1049 'qualiti':17,28,60,782,816 'rational':634 're':965 're-rend':964 'react':675,755,951,971 'read':650,1037 'readabl':379,947,949 'reason':317,536,975,1074 'reconsid':52 'record':525,630 'red':46,489 'red-green-refactor':488 'reduc':987 'refactor':313,491,718,722 'reimplement':1146 'reinstal':905 'reliabl':228 'remain':1117,1138 'remov':740 'render':689,959,966,1085 'replac':743 'report':885,1065 'reproduc':752 'reproduct':730,736 'requir':264,269,916,1003 'respons':78,86,248,592 'review':271 'root':202,436,440,683,719 'rule':73,237,296,362,1098 'run':788,857,891,897 'safe':468,862,863 'safeti':135,451 'scale':207 'script':894,901 'search':586 'section':639 'server':801 'signific':378 'similar':66,588,597,608,620 'simpl':383 'simplic':941 'singl':82,85 'site':726 'situat':915 'skill' 'skill-frontend-ai-guide' 'smaller':156 'solv':201 'source-shinpr' 'specif':7 'split':154 'srp':88 'stack':663 'stage':1013,1092 'start':495,910 'state':147,776,1057 'statement':277 'statetyp':1031 'stop':50 'structur':1063 'submiss':772 'suffici':479 'suppress':120 'surfac':195,431 'surface-level':194,430 'symptom':422,452,481,504,566,686 'symptomat':192 'target':1121 'task':532 'technic':8,24,33,42,124,170,502,611,917 'techniqu':15,644 'technolog':183,511 'test':386,480,498,834,838,839,841,855,858,861,864,898 'think':167 'three':75,298 'time':71,319,327,336,919,929,960 'timestamp':778 'toisostr':781 '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' 'trace':664 'tree':760 'troubleshoot':886 'true':546 'type':130,134,450,457,464,471,473,810,812 'type-check':809 'typescript':390,765,829 'ui':994 'uncertain':182 'uncertainti':503 'undefin':693 'understand':435,575,1035 'unexpect':107,506 'unknown':185,470 'unless':950 'unnecessari':963 'unplan':174,204 'unrel':741 'unus':1095,1100 'updat':711,714,727 'use':20,115,128,143,251,454,548,590,600,703,754,785,889,996,1107,1134 'user':408,770 'user-form-submiss':769 'useremailinput':397 'util':1124 'valid':361 'verif':557 'verifi':282 'version':116 'violat':72,84,96 'vite':907 'vitest':872 'vs':946 'why1':690 'why2':694 'why3':701 'why4':707 'why5':712 'whys':444,682 'without':102,434,478,521 'work':164,191,516,1143 'workflow':19,784 'write':65,273,925 'yagni':933 'yes':1108,1142,1147","prices":[{"id":"881f0752-15fc-4075-a541-461760a70861","listingId":"ab379109-c118-4685-8827-2627ba772b10","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:03.081Z"}],"sources":[{"listingId":"ab379109-c118-4685-8827-2627ba772b10","source":"github","sourceId":"shinpr/claude-code-workflows/frontend-ai-guide","sourceUrl":"https://github.com/shinpr/claude-code-workflows/tree/main/skills/frontend-ai-guide","isPrimary":false,"firstSeenAt":"2026-04-18T22:03:03.081Z","lastSeenAt":"2026-05-02T18:53:51.647Z"}],"details":{"listingId":"ab379109-c118-4685-8827-2627ba772b10","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"shinpr","slug":"frontend-ai-guide","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":"8a05065c41698eb79f50907efc9969a19b48799c","skill_md_path":"skills/frontend-ai-guide/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/shinpr/claude-code-workflows/tree/main/skills/frontend-ai-guide"},"layout":"multi","source":"github","category":"claude-code-workflows","frontmatter":{"name":"frontend-ai-guide","description":"Frontend-specific technical decision criteria, anti-patterns, debugging techniques, and quality check workflow. Use when making frontend technical decisions or performing quality assurance."},"skills_sh_url":"https://skills.sh/shinpr/claude-code-workflows/frontend-ai-guide"},"updatedAt":"2026-05-02T18:53:51.647Z"}}