dev

name: dev description: "Common development guidelines for all orchestrated sub-agents. Enforces modular development, systematic debugging, verification-before-completion, change logging, and code quality standards. Always injected by orchestrator." metadata: { "keywords": ["connector", "dashboard"]

}

Dev — Common Development Guidelines

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

§0.0 Work Classifier (C0-C5)

Classify every task before choosing process depth (DEV-CLASS-01). The class selects how much planning, reading, and verification the task deserves — never apply maximum process by default.

Tie-break (DEFAULT): when signals match two classes, the higher class wins. A conventional route→service→storage slice still counts as C2 even though it spans files; C3's "multiple modules" means crossing a module/package boundary beyond that conventional slice.

C4-promotion triggers override any fast path (DEV-ESCALATE-01): security, data deletion/migration, destructive ops, public contract change, release surface, permission model, new dependency/framework. Any of these promotes the affected part of the task to C4-level care — split it out rather than inflating the whole slice. Promotion alone does not force a user question; stopping to ask is required only for rules individually classed ESCALATE (§0.2).

§0.1 Patch Fast-Path (C0/C1)

For C0/C1 work (bounded by "one file, no new abstractions, local behavior" — a ≤5-line in-place edit is an example, not a limit):

• Skip: §0.5 convention discovery, §1.5 pre-write search, reference file reading
• Keep: §3 verification gate, §4 change documentation when a worklog/changelog file is provided, §5 safety rules (imports/exports), §7.2 static analysis
• Role skills: read only the SKILL.md routing table — skip references unless the table explicitly routes to one

This is scope guidance, not an exemption. Conventions visible in the touched file still apply even when proactive discovery is skipped. Promotion is behavioral, not territorial: a patch escalates when it can alter the behavior of an auth/payment/deletion or other DEV-ESCALATE-01 path — not merely because the file lives in such an area. A zero-behavior edit (comment, typo, log string) inside an auth file stays C0; any edit touching the executed logic of such a path is not C0/C1 — reclassify and read the relevant reference.

§0.2 Rule Classes

Every rule in the dev skill family carries one severity class. When a rule's class is not marked, treat prohibitions (⛔/MUST/NEVER) as STRICT and everything else as DEFAULT.

• STRICT — always applies; violating it blocks completion (safety, broken builds, secrets).
• DEFAULT — apply unless a documented, stated reason says otherwise.
• HEURISTIC — judgment guide; deviation needs no justification, just awareness.
• STYLE_SAMPLE — illustrative example or preset only. Examples illustrate acceptable choices but MUST NOT become universal requirements (DEV-STYLE-SAMPLE-01).
• ESCALATE — stop and ask the user before proceeding.

§0.3 Methodology Overlays (task_tags)

Methodologies are conditional overlays, never universal. They activate via dispatch task_tags, explicit user request, repo convention, or a matching strict trigger — required evidence applies only when the strict trigger applies (low-risk/local work uses the smallest proof that validates the claim, with the reduced scope stated).

Tags are normalized task_tags, not employee role values; the execution role stays frontend|backend|data|docs (PROMPT-ROUTING-01).

The boss sets task_tags at dispatch. With no tags, only strict triggers (self-assessed by the employee, reduced scope stated) activate overlays — legacy dispatches without the field behave identically. task_tags must be an array; a bare string is coerced to a single tag, and unknown tags are surfaced in the prompt, not silently dropped.

Ordinary product reference (on-demand)

For C2 ordinary product slices, the recipe lives in references/product/crud-product-development.md — read it when building a conventional feature slice, not for every task.

§0.4 Workflow Modes

The same rules flex by execution mode — know which one you are in: ordinary chat (direct work, C0-C2 typical) · strict PABCD (orchestrate P/A/B/C/D) · goal mode (self-advancing gates, evidence-backed checkpoints) · isolated employee (read-only verifier by default) · mutable employee (--mutable, scoped writes) · read-only review (no mutation, findings only) · docs-only work (no code gates, docs consistency checks instead).

Production surface (shared definition): a surface is production when it is deployed for real users beyond the author; prototypes, spikes, and internal demos are not. Skills that scope rules to "production-surface" concerns (e.g. dev-backend §5 envelope/OTel, dev-frontend §14 checklist) condition on this definition.

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 Ownership Map

Each rule area has exactly one canonical owner. Other skills may contain stubs but MUST NOT duplicate canonical content.

When updating a rule, update the canonical owner first, then verify stubs still point correctly.

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

Documentation Verification (Context7)

Before using any external library API, verify current syntax via Context7 MCP:

1. resolve-library-id — get the library ID (e.g., /vercel/next.js)
2. query-docs — fetch current docs for the specific API/feature

When to verify: using any API you haven't verified in this session, library version is pinned in package.json/requirements.txt, syntax or behavior seems uncertain, or the library had a major release in the past 6 months.

When to skip: language built-ins (Array.map, str.split), standard library (fs, os, path, http), syntax you just verified this session.

If Context7 MCP is unavailable: fall back to web search for official docs. Never rely on training data alone for library-specific API calls.

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 (DEFAULT — exceed only with a stated reason):

Blast Radius Limits

Each PR/changeset MUST be scoped to one logical change. Opportunistic rewrites, unrelated cleanup, and drive-by refactors go in separate PRs.

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.

1.5 Pre-Write Codebase Search Obligation

Rule: Before creating a new function, helper, type, component, constant, route, fixture, or module, search the codebase for an existing owner or equivalent implementation. No new abstraction may be introduced without search evidence. This section does not apply on the §0.1 fast path (C0/C1 — no new abstractions are being created).

Banned patterns:

• Creating utils.ts, helpers.ts, or common.ts without owner search
• Duplicating a type because import path was not obvious
• Creating parallel API clients for the same endpoint
• "I could not find it" without showing search terms

Search evidence required: When code is changed, include terms searched, files inspected, reuse decision, and new-code justification in the final response.

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:

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 (STRICT)

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.

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

Long external waits (cli-jaw runtime): when a verification gate depends on a long-running external process (CI run, deploy, remote build, web-ai session) and you are the boss/goal agent inside cli-jaw, do not block the turn polling it. Register a server-owned task and end the turn: cli-jaw bgtask add --cmd '["gh","run","watch","123","--exit-status"]' --prompt "CI done: {{result}} — verify and report" (web-ai: --preset web-ai --session $SID). The server re-invokes the boss with a [bgtask:*] prompt on completion. Local commands (tests, tsc, builds that finish in minutes) stay blocking — bgtask is for genuinely long external work.

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 (ESCALATE) — 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.

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.

7.2 Static Analysis Gate

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

Common Rule ↔ Prose Mapping

This table is not exhaustive — check project config for the canonical set.

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. Do not preload all references (HEURISTIC) — a backend task about caching doesn't need process-isolation.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, stacks/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.