- name
SKILL.md
The skill file stays in the publisher's repository.
Paste the copied command in a terminal. It installs this SKILL.md into that agent.
npx skills add shinpr/claude-code-workflows --skill ai-development-guide -a cursor -yPaste the copied command in a terminal. It installs this SKILL.md into that agent.
npx skills add shinpr/claude-code-workflows --skill ai-development-guide -a claude-code -yPaste the copied command in a terminal. It installs this SKILL.md into that agent.
npx skills add shinpr/claude-code-workflows --skill ai-development-guide -a codex -yPaste the copied command in a terminal. It installs this SKILL.md into that agent.
npx skills add shinpr/claude-code-workflows --skill ai-development-guide -a grok -ySend the copied message in a Grok Bot chat. The Bot fetches this SKILL.md from GitHub and adds it to the skills all your Bots share.
Install this skill: https://github.com/shinpr/claude-code-workflows/tree/HEAD/dev-skills/skills/ai-development-guideFrom the publisher
Inspect until the evidence identifies the lowest-total-complexity solution that delivers the required user, operator, or maintainer value while keeping the system correct and maintainable.
Judge total complexity across every activated surface: user decisions, settings, modes, concepts, outputs, persistent state, and implementation paths, together with their UX, runtime, implementation, testing, documentation, and maintenance cost. Compare only dimensions that differ between viable approaches. Prefer reuse or no new mechanism when it delivers the same required value and proof at lower total complexity.
Pause the affected decision and review the design when detecting the following patterns:
Make all errors visible and traceable with full context. Prioritize primary code reliability over fallback implementations. Excessive fallback mechanisms mask errors and make debugging difficult.
Infrastructure Layer:
Application Layer:
Review Triggers (require design review):
Another handler may remain when it covers a distinct failure mode with a documented recovery owner, state outcome, and observable signal.
Before Implementing Any Fallback:
AVOID: Silent fallback that hides errors
<handle error>:
return DEFAULT_VALUE // Error hidden, debugging impossible
PREFERRED: Explicit failure with context
<handle error>:
<attach operation context>
IF this boundary owns diagnosis: <log once>
<propagate error> // Re-throw exception, return Error, return error tuple
Adaptation: Use language-appropriate error handling (exceptions, Result types, error tuples, etc.)
Keep concrete implementations separate while their apparent similarity is accidental or their change reasons differ. Consolidate when repository evidence shows the same business rule, algorithm, validation contract, or coordinated change responsibility is maintained in multiple places.
Cases for Commonalization
Cases to Avoid Commonalization
Symptom: Fixing one error causes new errors Cause: Surface-level fixes without understanding root cause Avoidance: Identify root cause with 5 Whys before fixing
Symptom: Bypassing safety mechanisms (type systems, validation, contracts) Cause: Impulse to avoid correctness errors Avoidance: Use language-appropriate safety mechanisms (static checking, runtime validation, contracts, assertions)
Symptom: Many bugs after implementation Cause: Accepted behavior left without a test that proves it Avoidance: Prove each delivered behavior at the boundary where it is observed
Symptom: Dependent work fails, or workarounds accumulate, once an assumed premise proves false Cause: Treating an assumed capability, behavior, or existing implementation as fact Avoidance: When an unverified premise could invalidate the chosen approach, check it by the cheapest sufficient means before building dependent work on it. When results contradict the premise, reconsider the approach before patching its parts. Keep this reasoning in the active task; it needs no separate artifact.
Symptom: Duplicate implementations, architecture inconsistency, integration failures, adopting outdated patterns Cause: Insufficient understanding of existing code before implementation; referencing only nearby files without verifying representativeness Avoidance Methods:
Before executing quality checks, identify what quality mechanisms exist for the change area:
Discover the repository's configured quality entry points and the categories they cover. Use the categories below as the applicable evidence checklist:
Follow repository-declared command composition or ordering when it exists. Otherwise choose an order that respects command dependencies and provides useful feedback. Completion requires every applicable configured check to pass.
Complete these stages sequentially before implementation. For an isolated change with no public contract, data-flow, integration, or configuration impact, concise notes or search evidence are sufficient. Use the structured report for cross-boundary, high-risk, or multi-consumer changes.
1. Discovery - Identify all affected code:
2. Understanding - Analyze each discovered location:
3. Identification - Record the affected units, risks, and implementation order at the depth required by the change. For expanded analysis, use:
## Impact Analysis
### Direct Impact
- [Unit]: [Reason and modification needed]
### Indirect Impact
- [System]: [Integration path → reason]
### Data Flow
[Source] → [Transformation] → [Consumer]
### Risk Assessment
- High: [Complex dependencies, fragile areas]
- Medium: [Moderate coupling, test gaps]
- Low: [Isolated, well-tested areas]
### Implementation Order
1. [Start with lowest risk or deepest dependency]
2. [...]
Proceed when discovery and understanding cover the accepted outcome, governing boundaries, and required adjacent dependencies, and each material risk has an implementation, verification, or unresolved-decision disposition.
When an artifact made obsolete by the requested change is detected:
Required by the requested change? No → Preserve unless the change proves it obsolete
Yes → Working and compatible? Yes → Fix/Extend
No → Repair or replace with migration/rollback evidence
Principle: Prefer clean implementation over patching broken code
Applies technical decision criteria, anti-pattern detection, debugging, and quality gates for backend and frontend code. Use when implementing, reviewing, or diagnosing code, code smells, failures, or
---name: ai-development-guidedescription: Applies technical decision criteria, anti-pattern detection, debugging, and quality gates for backend and…---# dev-skills/skills/ai-development-guide/SKILL.mdOverview
Applies technical decision criteria, anti-pattern detection, debugging, and quality gates for backend and frontend code. Use when implementing, reviewing, or diagnosing code, code smells, failures, or implementation completeness.
FAQ
Download dev-skills/skills/ai-development-guide/SKILL.md from the publisher, or copy the path and open the repository. PlugMCP lists the skill and does not host the file.
The publisher keeps it at https://github.com/shinpr/claude-code-workflows.
Claude, Cursor, Codex, and Grok Build can read a SKILL.md you add from the publisher's repository. Grok Bot installs it when you send the skill's GitHub folder link in a chat.