lidge-jun/dev

Dev — Common Development Guidelines

Core rules applied to every sub-agent, regardless of role.

Companion Skills

This skill covers universal guidelines. For domain-specific work, also read the matching role skill's SKILL.md before writing code in that domain:

| Skill File | Injected When | Covers | | ---------------------------- | --------------------------------- | ---------------------------------------------------------------------------------------------- | | dev-frontend/SKILL.md | role=frontend | UI/UX implementation, design aesthetics, component architecture, responsive layouts, animation | | dev-backend/SKILL.md | role=backend | API design, architecture patterns, database optimization, error handling, middleware | | dev-data/SKILL.md | role=data | Data pipelines, ETL/ELT, data quality validation, SQL optimization, analysis & reporting | | dev-security/SKILL.md | Security-sensitive code, role=security | OWASP Top 10, auth hardening, input validation, secrets management, supply chain security | | dev-testing/SKILL.md | role=testing or testing phase | Test strategy, Playwright browser testing, coverage analysis, contract testing | | dev-debugging/SKILL.md | Debugging phase (phase 4) | Root cause analysis, boundary instrumentation, hypothesis testing, postmortem | | dev-code-reviewer/SKILL.md | Any agent, during code review | Review process, quality thresholds, antipattern detection, giving/receiving feedback |

When your task spans multiple domains (e.g., building an API endpoint that returns analyzed data), read each relevant skill file before starting.

---

0. Intent Clarification

When a request has ambiguous scope or unspecified technology, clarify before coding. If the user already specifies clear tech and scope (e.g. "React로 Drawer 만들어줘"), skip this step entirely.

How

1. Adapt depth to the question: vague/abstract → explain each option in detail. User seems to know the terms → brief trade-off comparison only.
2. Present options as <TechName> — <plain explanation>: include pros/cons relevant to THIS project. ⚠️ Flag options that are complex, expensive, or carry risk (e.g. memory leaks, operational overhead).
3. Recommend one with reasoning: "이 프로젝트는 ~이기 때문에 ~를 추천합니다." Always cite project context.
4. Let the user decide: "이걸로 갈까요?" — if the user picks a risky option, warn once, then respect the choice.

Over-engineering guard

Consider whether simpler alternatives exist before suggesting heavy frameworks. A 3-page portfolio probably doesn't need Next.js — but if the user has deployment, SEO, or CMS plans, it might. Use judgement, not absolute rules.

Limit

One confirmation round: 2-3 options → 1 recommendation → confirm → move on. Don't turn clarification into an interview.

---

0.5 Repository Convention Discovery

Before broad changes, inspect existing project conventions:

• Source layout: src/, app/, packages/, frontend/, backend/
• Source-of-truth docs/logs: structure/, docs/, architecture/, adr/, devlog/, plans/, changelogs
• Agent context: AGENTS.md, CLAUDE.md, .github/copilot-instructions.md, tool-specific instruction files
• JS/TS setup: package.json, tsconfig*, ESLint/Biome config, sibling file extensions
• Existing naming, test, module, and phase-document patterns
• Devlog phase documents: decade-range Jawdev numbering (00-09 research, 10-19 phase 1, etc.) — see dev-pabcd skill

MUST follow existing conventions when they are clear. MUST read existing structure/, devlog/, or other source-of-truth logs before broad implementation. MUST NOT create structure/, devlog/, AGENTS.md, docs folders, or new tooling silently in an existing repo.

If the repo is immature, undocumented, or inconsistent, propose a lightweight source-of-truth structure and ask for approval before creating it.

Broad Change Preview

Before broad changes, show a compact tree and planned touch points.

Broad change means any of:

• Creates or reorganizes directories
• Touches 5+ files
• Spans frontend + backend or multiple top-level packages
• Adds a new feature/module/service
• Adds project documentation or source-of-truth structure

Preview format:

• Current signals: detected stack and docs/conventions found
• Compact tree: max ~40 lines; omit node_modules, dist, build, .git
• Planned edits: files/folders to create or modify
• Convention decision: reuse existing structure, or ask before proposing new structure

---

1. Modular Development

Give every file, function, and class a single, clear responsibility.

Hard limits:

| Metric | Threshold | Action | | ------------------- | ----------- | ---------------------------------------- | | File length | >500 lines | Split into focused modules | | Function length | >50 lines | Extract helper functions | | Class methods | >20 methods | Split by responsibility | | Nesting depth | >4 levels | Flatten with early returns or extraction | | Function parameters | >5 | Use an options/config object |

Rules:

• Use ES Module (import/export) in JS/TS projects — CommonJS require() breaks tree-shaking and static analysis.
• One default export per file when the file has a primary purpose (JS/TS convention; other languages follow their idioms).
• Follow existing naming conventions in the project. Check sibling files before creating new ones.
• New files must match the directory structure and naming patterns already in use.
• For Jawdev/devlog phase documents, use decade-range numbering: 00-09 research/specs, 10-19 phase 1, 20-29 phase 2, etc. Never use bare filenames like PLAN.md, PHASES.md, or RCA.md. See dev-pabcd skill for full convention.

---

2. Systematic Debugging

Investigate the root cause before applying any fix — guessing leads to compounding rework.

For full debugging methodology — boundary instrumentation, pattern analysis, hypothesis testing, and postmortem — see dev-debugging/SKILL.md.

This section covers the emergency stop triggers every agent should recognize:

Red flags — stop and return to root cause investigation:

| Rationalization | Reality | | ---------------------------------------------- | ------------------------------------------------------- | | "Quick fix for now, investigate later" | First fix sets the pattern. Do it right from the start. | | "Just try changing X and see" | Guessing guarantees rework. | | "I don't fully understand but this might work" | Seeing symptoms ≠ understanding root cause. | | "Proposing solutions before investigating" | You haven't done Phase 1. | | "One more fix attempt" (after 2+ failures) | 3+ failures = architectural problem. |

If 3+ fix attempts fail: pause and reassess. Each fix revealing a new problem elsewhere signals an architectural issue, not a simple bug. Question fundamentals: Is this pattern sound? Are we sticking with it through inertia? Discuss with the user before attempting more fixes.

---

3. Verification Before Completion

Verify every completion claim with evidence. Run the relevant command fresh, read full output, and confirm the claim matches.

Verification gate (before any completion claim):

1. Identify — What command proves this claim?
2. Run — Execute fresh (not cached).
3. Read — Full output. Check exit code. Count failures.
4. Confirm — Does the output actually support the claim?
5. Report — State the claim with evidence attached.

| Claim | Requires | Not Sufficient | | ----------------------- | ------------------------------------- | ----------------------------- | | "Tests pass" | Test command output: 0 failures | Previous run, "should pass" | | "Build succeeds" | Build command: exit 0 | "Linter passed" | | "Bug fixed" | Original symptom verified resolved | "Code changed, assumed fixed" | | "Feature complete" | Each requirement checked line-by-line | "Tests pass" | | "Agent completed" | VCS diff shows actual changes | Agent report says "success" | | "Regression test works" | Red-green cycle verified | Test passes once |

Agent delegation: When sub-agents report success, verify independently: check VCS diff → verify changes exist → confirm behavior.

Red flags — unverified claims creeping in:

• Using words like "should", "probably", "seems to"
• Expressing satisfaction before verification ("Great!", "Done!")
• Relying on partial verification or a previous run
• Trusting agent success reports without independent verification
• Thinking "just this once"

---

4. Change Documentation

When a worklog or changelog file is provided, record every change in this format:

### [filename] — [reason for change]
- **Changes**: what was modified and why
- **Impact**: modules that import or depend on this file
- **Verification**: how the change was tested (command + result)

Keep entries factual and concise. One entry per file changed.

---

5. Safety Rules

• Preserve existing exports — other modules may depend on them. Deprecate first if removal is needed.
• Verify imports exist before adding import statements. Confirm the target file and export are real.
• Externalize configuration — use config files or environment variables. Place magic strings and numbers in named constants.
• Handle all async errors explicitly — surface failures at a clear boundary. In JS/TS backend code, the Result pattern (neverthrow) may replace per-call try/catch when failures are surfaced at a verified boundary (see dev-backend/SKILL.md §3). In other cases, use try/catch and log with context (console.error('[module]', error.message)).
• Confirm before destructive operations — deleting files, dropping tables, resetting state, or clearing caches require explicit user approval.

---

6. Code Quality Signals

Watch for these anti-patterns and fix immediately. For the full detection catalog and review-specific guidance, see dev-code-reviewer/SKILL.md §3.

| Anti-Pattern | Symptom | Fix | | -------------------------- | ----------------------------------- | ------------------------------------- | | God class | >20 methods, mixed responsibilities | Split by domain into focused classes | | Long method | >50 lines, does multiple things | Extract into named helper functions | | Deep nesting | >4 levels of if/for/try | Early returns, guard clauses, extract | | Magic numbers | Hardcoded 86400, 1024, 3 | Named constants with clear intent | | Stringly typed | Strings where enums/types belong | Define explicit types or enums | | Missing error handling | No catch, no input validation | Add try/catch, validate all inputs | | Floating promises | async call without await | Always await or handle rejection | | Copy-paste code | Same logic in 2+ places | Extract shared function, import it |

---

7. Type Safety & Static Analysis

7.0 JS/TS Source File Default

For new JavaScript/TypeScript source files, prefer TypeScript:

• Use .ts for logic and .tsx for typed UI components when the project already supports TypeScript or is greenfield JS/TS.
• Use .js/.jsx only when the repo is clearly JS-only, build/runtime constraints require JS, or the user asks for JS.
• Do not introduce TypeScript tooling, convert existing JS, or change tsconfig without user approval.

New TypeScript MUST be strict-compatible from the first patch:

• No implicit any.
• Explicit any requires a nearby justification comment.
• Prefer unknown plus narrowing over any.
• Type exported function parameters and return values.
• Handle null/undefined deliberately.
• Avoid code that only passes because strict is disabled.

Verification:

• Run the project's configured typecheck when available.
• If TypeScript is present but no typecheck script exists, use the closest safe command such as tsc --noEmit.
• If strict compatibility cannot be verified, state that explicitly.

7.1 Type Annotations

Add explicit type annotations to all function signatures, return types, and non-trivial variables.

| Language | Rule | | ---------- | ----------------------------------------------------------------------------------- | | TypeScript | strict: true in tsconfig. Avoid implicit any; explicit any requires a line comment with justification. | | Python | Type hints on all function params and returns (def fetch(url: str) -> Response:). | | Go | Already enforced by compiler — ensure exported types have doc comments. | | C# / Java | Use nullability annotations (?, @Nullable). Avoid raw Object or dynamic. | | General | If the language supports a strict/pedantic mode, enable it. |

7.2 Static Analysis Gate

After every code change, run the project's static analysis toolchain as part of the verification gate (Section 3).

| Toolchain | Command | Must Pass | | -------------- | ------------------------------------- | ---------------------------- | | TypeScript | tsc --noEmit | Zero errors | | Python (typed) | mypy . or pyright | Zero errors on changed files | | ESLint / Biome | npx eslint . or npx biome check . | Zero errors | | Go | go vet ./... | Zero issues | | Rust | cargo clippy -- -D warnings | Zero warnings | | C# | dotnet build /warnaserror | Zero warnings |

If no static analysis tool is configured in the project, recommend one to the user — but do not add tooling without approval.

7.3 Escape Hatches

When bypassing the type system is unavoidable:

• Add a comment explaining why the escape is needed.
• Scope it minimally — cast at the narrowest point, not the broadest.
• Prefer assertion functions over raw casts (assertIsString(x) > x as string).
• TypeScript: as unknown as T double-cast requires a linked issue or TODO.
• Python: # type: ignore[code] must specify the exact mypy error code.

---

8. Token Budget Awareness

When multiple skills are injected simultaneously (e.g., dev + dev-backend + dev-security), token consumption grows quickly. Follow these rules to stay efficient:

Tiered reference loading:

1. Always read: SKILL.md files for injected skills (these are the orchestrators)
2. Read on demand: Reference files (references/) — only load when the task touches that specific topic
3. Never preload all references — a backend task about caching doesn't need streaming.md

Example: For "Add Redis caching to user endpoint":

• Read: dev/SKILL.md + dev-backend/SKILL.md + dev-backend/references/core/caching.md
• Skip: api-design.md, architecture.md, observability.md, database.md (unless the task touches those areas)

Cost awareness for sub-agents: Each sub-agent receives its own copy of injected skills. Minimize skills injected per sub-agent — give only what's needed for that specific sub-task.

---