JinDaGe - kubemin-agent-code Skill Details

Scope

This skill defines the working agreement for assisting with the KubeMin-Agent project (Python AI Agent), including communication norms, code change workflow, testing expectations, naming conventions, documentation synchronization, and PR hygiene.

Rule Priority

When rules conflict, apply this priority order:

Security > Correctness > Performance
Explicit user instructions > SKILL rules > General best practices
Single-turn delivery (low risk) > Multi-turn confirmation
Existing project conventions > General Python conventions

1. Risk Assessment & Delivery Strategy

Risk Levels

| Level | Criteria | Delivery Strategy | |-------|----------|-------------------| | LR0 (Pure Internal) | No public API/behavior changes, no persistence/concurrency/security involvement, single module scope, behavior-preserving refactors or non-functional changes | Single-turn delivery | | LR1 (Limited Domain) | Touches persistence/concurrency/security BUT satisfies all LR1 constraints below | Single-turn delivery (with verification) | | Medium/High | API/behavior changes, schema changes, new shared concurrency state, security boundary expansion, cross-module impact | Confirm plan first |

LR1 Constraints (must satisfy ALL)

Scope limit: ≤3 files OR ≤200 LOC changed
Localized bugfix/security fix with no API/contract changes
Testable or verifiable with reproducible steps
No schema changes (migrations, serialization format)
No new shared concurrency state (e.g., new global dict + lock)
No permission/access scope expansion

LR1 exclusions: Schema changes, cross-module protocol/serialization format changes, new shared concurrency state, relaxed auth/access scope.

Efficiency Rules

Ambiguous but low-risk: Proceed with clearly stated assumptions. Ask only when assumptions may affect correctness, safety, or public behavior.
Single-turn preference: Deliver plan + code + tests/verification + docs/PR in one response unless medium/high-risk confirmation required.
Batch processing: Multiple low-risk changes in same session → one combined delivery.

Delivery Block Order

1. Risk Assessment (LR0/LR1/Medium/High)
2. Assumptions (if any ambiguity)
3. Plan (what will change)
4. Patch (code changes)
5. Tests/Verification (if meaningful)
6. Docs/PR (only if required or requested)

2. Communication

Communicate with user in Chinese by default
Documentation defaults to Chinese; English only when explicitly requested
Provide English for specific artifacts only when user requests

3. Code Standards

Naming

Follow Python PEP 8 conventions: snake_case for functions/variables/modules, CamelCase for class names
Prefer existing naming patterns in the project
Names should express intent clearly; avoid abbreviations (except project-standard ones)

Style

Favor simplicity; avoid over-engineering
Small functions, composable, early returns
Async code uses async/await, properly propagate cancellation and timeouts
Errors use custom exceptions with traceable context information
Type annotations: add complete Type Hints for all public interfaces

Constants & Configuration

| Type | Location | |------|----------| | Single-package constants | Nearest package (e.g., agent/constants.py) | | Cross-domain constants | config/constants.py or project's existing public constants location (avoid reverse-depending on business packages) | | Runtime-configurable values | config/ package, using Pydantic Settings |

Rule: Reusable strings/enums should be centralized, avoid scattered hard-coding. Only runtime-configurable items belong in config/.

Project Architecture Conventions

| Module | Responsibility | |--------|---------------| | control/ | Control plane (Scheduler, Validator, AgentRegistry, AuditLog) | | agents/ | Sub-agents (BaseAgent, K8sAgent, WorkflowAgent, GeneralAgent, GameTestAgent) | | agent/ | Agent runtime infrastructure (Loop, Context, Memory, Skills) | | agent/tools/ | Tool registration and execution (Base, Registry, concrete tool implementations) | | providers/ | LLM Provider abstraction and concrete implementations | | bus/ | Message bus (decouples Channel from Agent) | | channels/ | Channel integration (CLI, Telegram, etc.) | | session/ | Session management and persistence | | config/ | Configuration model and loading | | cron/ | Scheduled task scheduling | | heartbeat/ | Heartbeat detection and proactive wake-up | | skills/ | Built-in skills | | cli/ | CLI command entry | | utils/ | Common utility functions |

Self-Review

After implementation: eliminate duplication, reduce nesting, remove redundant branches, check type annotation completeness.

4. Testing Requirements

| Change Type | Test Strategy | |-------------|---------------| | LR0 (non-functional) | Tests only if meaningful | | LR0 (logic changes) | Minimal unit tests covering modified logic | | LR1 changes | Unit tests OR verification steps | | Medium/High risk | Full coverage: parameterized tests, edge cases, failure paths |

Test Exemption & Alternatives

When unit tests are impractical, document:

Why not testable: e.g., handler layer with complex external dependencies
Alternative verification (must be reproducible and copy-pasteable):
- Exact commands to run
- Expected output/behavior

Handler layer exemption: If handler layer has no unit tests, must provide:

Unit test coverage for the underlying service/domain layer (if affected by this change), OR
Reproducible curl/CLI/integration commands with expected results

Acceptable exemption cases:

Log/comment/formatting changes (testing adds no value)
Handler code with complex dependencies (but service layer must be covered)

Test Organization

Use pytest as the testing framework
Keep tests for same feature in one test file
Extend existing test_*.py files; create new only when no suitable file exists
Use conftest.py to manage shared fixtures

5. Documentation Updates

Trigger Conditions

| Change Impact | Requires docs/? | |---------------|-------------------| | User-visible behavior/API/config/ops | ✅ Yes | | Contract logs | ✅ Yes | | Debug/diagnostic logs | ❌ No | | Error contract changes | ✅ Yes | | Default value/semantic changes | ✅ Yes | | Pure internal refactoring / non-functional | ❌ No |

Documentation Content (when required)

Summary, motivation, key design decisions
API/behavior changes
Test coverage description
Test execution commands

Organization Rules

Merge docs for same PR into one Markdown file per topic
If repository lacks docs/ directory → confirm before creating; otherwise update existing structure
Language: Chinese by default

6. PR Guidelines

Format

Title: Clear imperative sentence
Body: Summary / Changes / Testing / Notes
⚠️ Use real newlines, not \n escape sequences

When to Provide PR Description

User explicitly requests ("give me PR description" / "preparing to submit PR")
Change requires docs/examples (complete delivery scenario)
Default: title + brief summary only

Updates

Only update PR description when new commits change scope or materially affect user-visible behavior/API, configuration, or risk.

7. Dependency Management

Core Dependency Conventions

| Purpose | Recommended Library | |---------|-------------------| | CLI framework | typer | | LLM gateway | litellm | | Config model | pydantic + pydantic-settings | | HTTP client | httpx | | Logging | loguru | | Cron scheduling | croniter | | Terminal output | rich | | Async WebSocket | websockets |

Rules

New dependencies must justify their inclusion, prefer reusing existing dependencies
Use pyproject.toml to manage dependencies
Use hatchling as the build backend

8. Anti-patterns

| ❌ Don't | ✅ Do | |----------|-------| | Abuse LR1 for schema/shared-state changes | Use LR1 only within defined constraints | | Skip tests without reproducible alternative | Provide copy-pasteable verification commands | | Document every log change | Only document contract logs | | Put cross-domain constants in random packages | Use config/constants.py for shared constants | | Always generate full docs/PR | Only when required or requested | | Bypass AgentLoop to modify flow directly | New capabilities must be attached under existing interfaces | | Expose sensitive info in tool returns | API Keys only read from config or env vars |

9. Pre-Delivery Checklist

[ ] Risk level (LR0/LR1/Medium/High) correctly assessed?
[ ] LR1 constraints verified (≤3 files, no schema/shared-state changes)?
[ ] Delivery block order followed?
[ ] Tests provided OR reproducible verification documented?
[ ] Contract logs declared before requiring docs?
[ ] Docs/PR only if required?
[ ] Type annotations complete?
[ ] async/await usage correct?

Decision Flow

Receive request → Assess risk
    │
    ├── LR0 (Pure Internal)
    │     └── Single-turn: Plan + Patch + Tests (if meaningful) + Docs (if required)
    │
    ├── LR1 (Limited Domain) — verify constraints first
    │     ├── ≤3 files, ≤200 LOC?
    │     ├── No schema/shared-state/auth-expansion?
    │     └── Yes → Single-turn: Plan + Patch + Tests/Verification + Docs (if required)
    │
    └── Medium/High
          └── Confirm plan → User approval → Implement
                  │
                  ├── Affects public API? → Generate examples/
                  │     (includes defaults, pagination)
                  │
                  └── User-visible change? → Generate docs/
                        (contract logs only)

10. Iterative Improvement Process

This SKILL.md is a living document, continuously improved through real development feedback.

Improvement Triggers

| Trigger Scenario | Action | |-----------------|--------| | User reports recurring issues found in review | → Analyze root cause → Propose new/modified rules → Update SKILL.md | | Multiple review rounds still produce new issues | → Categorize issues → Add to "Lessons Learned" → Strengthen checklist | | Existing rules cause low efficiency | → Discuss simplification → Adjust rules → Record change reason | | Architecture evolution makes conventions outdated | → Update architecture convention table → Sync context-index.md |

Improvement Flow

User reports issue → Analyze if systemic
    │
    ├── One-off issue → Fix code only, don't change SKILL
    │
    └── Systemic/recurring issue → Propose SKILL improvement
          │
          ├── 1. Identify issue category (naming/architecture/security/testing/performance/…)
          ├── 2. Propose specific rule changes (for user confirmation)
          ├── 3. After user confirms, update corresponding SKILL.md section
          ├── 4. Add to "Lessons Learned" section
          └── 5. Record in "Changelog"

Proactive Suggestion Timing

After each code implementation, proactively suggest SKILL.md improvements if:

Repeatedly hesitated on design decisions during implementation (indicates rules are unclear)
Bypassed a rule in the code (indicates rule may be unreasonable or needs exception clause)
Discovered quality risk points not covered by existing rules

11. Lessons Learned (Review Retrospective)

This section records recurring issues and pitfalls discovered during reviews, for proactive avoidance in future development. Each entry includes: Problem Description, Root Cause Analysis, Mitigation Measures.

[LESSON-001] No Emoji in Documentation

Date Discovered: 2026-02-25
Problem: Design document used emoji characters in module structure comments, reducing professionalism
Root Cause: Default tendency to use emoji for visual categorization in code comments
Mitigation: All documentation and code comments must use plain text descriptions only. No emoji characters in any project artifacts including SKILL.md, design docs, README, and inline comments
Related Rule: Section 5 (Documentation Updates) - implicit formatting standard

[LESSON-002] Must Read SKILL.md Before Every Task

Date Discovered: 2026-02-25
Problem: Implemented GameTestAgent without re-reading SKILL.md, resulting in: missing type annotations on internal methods, hardcoded magic numbers instead of constants, architecture convention table not updated for new modules
Root Cause: Relied on "memory impression" of SKILL.md instead of actually reading it before implementation
Mitigation: Before every code implementation task, explicitly read SKILL.md first. After implementation, self-review against the Pre-Delivery Checklist (Section 9)
Related Rule: Section 9 (Pre-Delivery Checklist), Section 3 (Code Standards - Type Annotations, Constants)

12. Changelog

| Version | Date | Changes | Trigger | |---------|------|---------|---------| | v1.0 | 2026-02-25 | Initial version: complete development standards | Project initialization | | v1.1 | 2026-02-25 | Added iterative improvement process, lessons learned section, changelog | User requested continuous improvement capability for Skills | | v1.2 | 2026-02-25 | Translated entire SKILL.md to English for better readability | User requested English version | | v1.3 | 2026-02-25 | Added LESSON-001: no emoji in documentation | User feedback during design doc review | | v1.4 | 2026-02-25 | Added LESSON-002: must read SKILL.md before every task; updated architecture table with control/ and agents/ modules | Self-review after GameTestAgent implementation |