agentleFS
atilladenizatilladeniz/Kubeli/.claude/skills/refactor/SKILL.md

refactor

Skill387 starsChanged 9 months agoMITView on GitHub

Refactors code following Ousterhout's design principles. Analyzes complexity, creates prioritized refactoring plan, and executes with safety-first approach. Optimized for Vite/React, Tauri/Rust, Zustand stack.

195 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use ascii-diagram, debug-fix and 10 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • SethGammonSkill

    ascii-diagram

    Generate perfectly aligned ASCII diagrams — architecture, flow, sequence, box-and-arrow. Uses a programmatic character-grid approach so alignment is guaranteed by math, not token prediction. Includes post-render verification.

    Also in 4 projects that use this

  • zebbernSkill

    debug-fix

    Find and fix a bug or issue — from any source (GitHub issue, error message, user report, or observed behavior)

    Also in 4 projects that use this

  • parcadeiSkill

    agent-context-isolation

    Agent Context Isolation

    Also in 3 projects that use this

  • parcadeiSkill

    agentica-infrastructure

    Reference guide for Agentica multi-agent infrastructure APIs

    Also in 3 projects that use this

  • +8 more from parcadei

The file

Show its rules and text

We split this skill into the rules it gives an agent

15 rules. 0 are common, 14 are distinctive, and 1 is very specific to this project.

  • 0

    Common

    Most of the 168 edited versions we read keep these.

  • 14

    Distinctive

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Before any refactoring, analyze the code against these 15 Ousterhout principles:

    line 25
  2. Distinctive:

    Write characterization tests first

    line 56
  3. Distinctive:

    Test the component as a black box

    line 57
  4. Distinctive:

    Eine Aufgabe: - Do ONE thing and do it well

    line 142
  5. Distinctive:

    Eine Abstraktionsebene: - Don't mix abstraction levels

    line 143
  6. Distinctive:

    Stepdown Rule: - Read code top-down like a story

    line 144
  7. Distinctive:

    Max 3 Arguments: - Prefer 0-2, use object for more

    line 145
  8. Distinctive:

    Every time you touch code:

    line 207
  9. Distinctive:

    Add one missing test

    line 211
  10. Very specific:

    Run /software-design-review on target code

    line 1066
  11. Distinctive:

    Write the interface comment FIRST

    line 1073
  12. Distinctive:

    If not, write characterization tests

    line 1077
  13. Distinctive:

    Run tests to confirm green

    line 1078
  14. Distinctive:

    Run tests after each change

    line 1082
  15. Distinctive:

    Commit after each working step

    line 1083

“Common” is measured: kept by at least 6 in 10 of the 168 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Strategic Refactoring Skill

You are a senior software architect performing strategic refactoring based on John Ousterhout's "A Philosophy of Software Design" principles.

Your Goal: Transform code to reduce complexity while maintaining functionality. Every change should make the system look like it was designed with this feature in mind from the start.

Kubeli Tech Stack

  • Frontend: Vite 7+, React 19, TypeScript
  • Desktop: Tauri 2.0 (Rust backend)
  • State: Zustand
  • Styling: Tailwind CSS
  • K8s Client: kube-rs (Rust)

Phase 1: Analysis (Use /software-design-review principles)

Before any refactoring, analyze the code against these 15 Ousterhout principles:

  1. Strategic vs. Tactical Programming
  2. Module Depth (Deep vs. Shallow)
  3. Somewhat General-Purpose (Generalization)
  4. Different Layers, Different Abstractions
  5. Information Hiding & Leaks
  6. Pull Complexity Downward
  7. Together or Separate?
  8. Define Errors Out of Existence
  9. Design Twice
  10. Consistency
  11. Code Should Be Obvious
  12. Comments & Documentation
  13. Names
  14. Write Comments First
  15. Modifying Existing Code

Phase 2: Safety Checklist

Before ANY refactoring:

  • Tests exist for the code being refactored
  • All tests pass currently
  • Code is committed (clean git state)
  • You understand what the code does (read it first!)

If tests don't exist:

  1. Write characterization tests first
  2. Test the component as a black box
  3. Validate end results, not implementation details

Phase 3: Clean Code Smells Checklist (Robert Martin)

In addition to Ousterhout's principles, check for these code smells:

Comments (C1-C5)

CodeSmellFix
C1Ungeeignete Informationen (Change history, author info)Remove, use git
C2Überholte KommentareUpdate or delete
C3Redundante KommentareDelete if code is self-explanatory
C4Schlecht geschriebene KommentareRewrite clearly
C5Auskommentierter CodeDelete (git has history)

Functions (F1-F4)

CodeSmellFix
F1Zu viele Argumente (>3)Use object parameter
F2Output-ArgumenteReturn value instead
F3Flag-Argumente (boolean params)Split into two functions
F4Tote Funktionen (never called)Delete

General (G1-G36) - Most Important

CodeSmellFix
G2Offensichtliches Verhalten fehltImplement expected behavior
G3Falsches Verhalten an GrenzenAdd boundary tests
G5Duplizierung (DRY)Extract common code
G6Falsche AbstraktionsebeneMove to correct layer
G8Zu viele Informationen (large interface)Hide details, minimize API
G9Toter CodeDelete
G10Vertikale Trennung (related code far apart)Move together
G11InkonsistenzFollow established patterns
G13Künstliche KopplungDecouple unrelated code
G14Funktionsneid (Feature Envy)Move method to correct class
G16Verdeckte Absicht (obscure code)Make obvious
G17Falsche ZuständigkeitMove to responsible module
G23If/Else statt PolymorphismusUse polymorphism
G25Magische ZahlenNamed constants
G28Bedingungen nicht eingekapseltExtract to named function
G29Negative BedingungenUse positive conditions
G30Mehr als eine AufgabeSplit function
G31Verborgene zeitliche KopplungenMake dependencies explicit
G33Grenzbedingungen nicht eingekapseltEncapsulate bounds
G34Mehrere Abstraktionsebenen gemischtOne level per function
G36Transitive Navigation (Law of Demeter)Don't talk to strangers

Names (N1-N7)

CodeSmellFix
N1Nicht deskriptivRename to describe purpose
N2Falsche AbstraktionsebeneMatch name to abstraction level
N4Nicht eindeutigMake unambiguous
N5Zu kurz für großen ScopeLonger names for wider scope
N7Nebeneffekte nicht im NamenInclude side effects in name

Tests (T1-T9)

CodeSmellFix
T1Unzureichende TestsAdd more tests
T3Triviale Tests übersprungenTest everything
T5Grenzbedingungen nicht getestetAdd boundary tests
T6Bug-Nachbarschaft nicht getestetTest around bugs
T9Langsame TestsOptimize test speed

F.I.R.S.T. Test Principles

  • Fast: Tests should run quickly
  • Independent: Tests shouldn't depend on each other
  • Repeatable: Same result every time
  • Self-Validating: Boolean output (pass/fail)
  • Timely: Written before/with production code

Clean Code Function Rules

  1. Klein! Functions should be small (ideally < 20 lines)
  2. Eine Aufgabe - Do ONE thing and do it well
  3. Eine Abstraktionsebene - Don't mix abstraction levels
  4. Stepdown Rule - Read code top-down like a story
  5. Max 3 Arguments - Prefer 0-2, use object for more
// BEFORE: Too many args, mixed abstraction levels
async function processPod(
  namespace: string,
  name: string,
  action: string,
  force: boolean,
  gracePeriod: number,
  callback: () => void
) {
  const pod = await invoke('get_pod', { namespace, name });
  if (action === 'delete') {
    if (force) {
      await invoke('force_delete', { namespace, name });
    } else {
      await invoke('delete', { namespace, name, gracePeriod });
    }
  }
  callback();
}

// AFTER: Single purpose, one abstraction level
interface PodActionRequest {
  pod: PodRef;
  action: PodAction;
}

async function executePodAction({ pod, action }: PodActionRequest): Promise<void> {
  const handler = getPodActionHandler(action);
  await handler.execute(pod);
}

Law of Demeter (G36: Transitive Navigation)

Principle: A method should only call methods on:

  • Its own object (this)
  • Objects passed as parameters
  • Objects it creates
  • Its direct component objects
// VIOLATES Law of Demeter: "Train wreck"
const street = user.getAddress().getCity().getStreet();

// BETTER: Tell, don't ask
const street = user.getStreetAddress();

// Kubeli Example:
// BAD: Navigating through objects
const podName = store.getState().cluster.selectedPod.metadata.name;

// GOOD: Direct access with selector
const podName = useSelectedPodName();

Pfadfinder-Regel (Boy Scout Rule)

"Leave the code cleaner than you found it."

Every time you touch code:

  • Fix one small thing
  • Improve one name
  • Extract one function
  • Add one missing test

Phase 4: Stack-Specific Refactoring Patterns

Vite/React (Frontend)

Component Organization:

// BEFORE: Monolithic component with mixed concerns
export function PodList({ namespace }: Props) {
  const [pods, setPods] = useState([]);
  const [filter, setFilter] = useState('');
  useEffect(() => { fetchPods().then(setPods); }, []);
  return (
    <div>
      <input value={filter} onChange={e => setFilter(e.target.value)} />
      <ul>{pods.filter(p => p.name.includes(filter)).map(p => <PodItem pod={p} />)}</ul>
    </div>
  );
}

// AFTER: Separate data from presentation, use Zustand
// stores/resource-store.ts
export const useResourceStore = create((set) => ({
  pods: [],
  fetchPods: async (ns) => { /* ... */ },
}));

// components/PodList.tsx
export function PodList() {
  const pods = useResourceStore(s => s.pods);
  const [filter, setFilter] = useState('');
  return <ul>{pods.filter(p => p.name.includes(filter)).map(p => <PodItem pod={p} />)}</ul>;
}

Anti-Patterns to Fix:

SmellRefactoring
Props drilling through 3+ levelsUse Zustand store or Context
Giant utils.ts fileSplit into logical modules in lib/
Inline Tauri invoke() callsCentralize in lib/tauri/commands/
State in components that should be globalMove to Zustand store

Zustand (State Management)

Selective State Access:

// BEFORE: Re-renders on ANY state change
function PodCount() {
  const store = useClusterStore(); // BAD: subscribes to everything
  return <span>{store.pods.length}</span>;
}

// AFTER: Only re-renders when pods change
function PodCount() {
  const podCount = useClusterStore((s) => s.pods.length); // GOOD: selective
  return <span>{podCount}</span>;
}

Modular Stores with Slices:

// BEFORE: Monolithic store
const useStore = create((set) => ({
  pods: [],
  deployments: [],
  services: [],
  selectedPod: null,
  selectedDeployment: null,
  // ... 50 more properties
}));

// AFTER: Composable slices
// stores/pods-slice.ts
export const createPodsSlice = (set, get) => ({
  pods: [],
  selectedPod: null,
  fetchPods: async (ns) => { ... },
  selectPod: (id) => set({ selectedPod: id }),
});

// stores/deployments-slice.ts
export const createDeploymentsSlice = (set, get) => ({
  deployments: [],
  fetchDeployments: async (ns) => { ... },
});

// stores/index.ts
export const useStore = create((...a) => ({
  ...createPodsSlice(...a),
  ...createDeploymentsSlice(...a),
}));

Custom Hook Abstraction:

// BEFORE: Direct store access everywhere
function PodDetails({ id }: Props) {
  const pods = useClusterStore((s) => s.pods);
  const pod = pods.find(p => p.id === id);
  // ...
}

// AFTER: Domain-specific hooks
// hooks/usePod.ts
export function usePod(id: string) {
  return useClusterStore((s) => s.pods.find(p => p.id === id));
}

// components/PodDetails.tsx
function PodDetails({ id }: Props) {
  const pod = usePod(id);
  // ...
}

Tauri 2.0 / Rust (Backend)

Command Organization:

// BEFORE: All commands in one file
// src-tauri/src/main.rs
#[tauri::command]
fn get_pods() { ... }
#[tauri::command]
fn get_deployments() { ... }
#[tauri::command]
fn get_services() { ... }
// ... 50 more commands

// AFTER: Modular command structure
// src-tauri/src/commands/mod.rs
pub mod pods;
pub mod deployments;
pub mod services;

// src-tauri/src/commands/pods.rs
#[tauri::command]
pub async fn get_pods(state: State<'_, AppState>, namespace: &str) -> Result<Vec<Pod>, Error> {
    let client = state.client_manager.get_client()?;
    client.list_pods(namespace).await
}

// src-tauri/src/main.rs
fn main() {
    tauri::Builder::default()
        .invoke_handler(tauri::generate_handler![
            commands::pods::get_pods,
            commands::pods::delete_pod,
            commands::deployments::get_deployments,
        ])
        .run(tauri::generate_context!())
        .expect("error running app");
}

Separation: main.rs vs lib.rs:

// BEFORE: Logic in main.rs
// src-tauri/src/main.rs
fn main() {
    // 500 lines of logic...
}

// AFTER: main.rs only handles startup, lib.rs has logic
// src-tauri/src/main.rs
fn main() {
    kubeli_lib::run();
}

// src-tauri/src/lib.rs
pub mod commands;
pub mod k8s;
pub mod state;

pub fn run() {
    tauri::Builder::default()
        .manage(state::AppState::new())
        .invoke_handler(tauri::generate_handler![...])
        .run(tauri::generate_context!())
        .expect("error running app");
}

Rust Refactoring Patterns:

// BEFORE: Tuple returns (hard to understand)
fn get_cluster_info() -> (String, bool, u32) {
    (context_name, is_connected, node_count)
}
let (a, b, c) = get_cluster_info(); // What is a, b, c?

// AFTER: Struct with meaningful names
struct ClusterInfo {
    context_name: String,
    is_connected: bool,
    node_count: u32,
}
fn get_cluster_info() -> ClusterInfo { ... }
let info = get_cluster_info();
println!("Connected: {}", info.is_connected);
// BEFORE: if-else chains
if status == "Running" { ... }
else if status == "Pending" { ... }
else if status == "Failed" { ... }

// AFTER: Pattern matching with enum
enum PodStatus { Running, Pending, Failed, Unknown }

match pod.status {
    PodStatus::Running => { ... }
    PodStatus::Pending => { ... }
    PodStatus::Failed => { ... }
    PodStatus::Unknown => { ... }
}
// BEFORE: Manual error handling everywhere
fn get_pod(name: &str) -> Result<Pod, Error> {
    let pods = self.list_pods()?;
    for pod in pods {
        if pod.name == name {
            return Ok(pod);
        }
    }
    Err(Error::NotFound)
}

// AFTER: Iterator methods with Option/Result
fn get_pod(&self, name: &str) -> Option<&Pod> {
    self.pods.iter().find(|p| p.name == name)
}

// Or with Result if error info needed:
fn get_pod(&self, name: &str) -> Result<&Pod, Error> {
    self.pods.iter()
        .find(|p| p.name == name)
        .ok_or_else(|| Error::PodNotFound(name.to_string()))
}

Minimize Public API Surface:

// BEFORE: Everything public
pub struct KubeClientManager {
    pub clients: HashMap<String, Client>,
    pub current_context: String,
    pub config: KubeConfig,
}

// AFTER: Minimal public API, private internals
pub struct KubeClientManager {
    clients: HashMap<String, Client>,    // private
    current_context: String,              // private
    config: KubeConfig,                   // private
}

impl KubeClientManager {
    pub fn new() -> Result<Self, Error> { ... }
    pub fn get_client(&self) -> Result<&Client, Error> { ... }
    pub fn switch_context(&mut self, name: &str) -> Result<(), Error> { ... }
    // Internal methods stay private
}

Tauri 2.0 Enterprise Patterns

Command Layer Pattern (Thin Handlers → Service Layer):

// BEFORE: Fat command with business logic
#[tauri::command]
pub async fn create_user(name: String, email: String) -> Result<User, String> {
    // Validation here...
    // Database access here...
    // Business logic here...
    // 100+ lines of mixed concerns
}

// AFTER: Thin handler → Service layer
// src/commands/user_commands.rs
#[tauri::command]
pub async fn create_user(name: String, email: String) -> Result<User, AppError> {
    user_service::create_user(&name, &email).await
}

// src/services/user_service.rs
pub async fn create_user(name: &str, email: &str) -> Result<User, AppError> {
    validate_email(email)?;
    let user = User::new(name, email);
    repository::save_user(&user).await?;
    Ok(user)
}

Error Handling (thiserror + Serialize for IPC):

use thiserror::Error;
use serde::Serialize;

#[derive(Error, Debug)]
pub enum AppError {
    #[error("Database error: {0}")]
    Database(#[from] sqlx::Error),

    #[error("File not found: {path}")]
    FileNotFound { path: String },

    #[error("Kubernetes error: {0}")]
    Kube(#[from] kube::Error),

    #[error(transparent)]
    Other(#[from] anyhow::Error),
}

// CRITICAL: Implement Serialize for Tauri IPC
impl Serialize for AppError {
    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
    where S: serde::Serializer {
        serializer.serialize_str(&self.to_string())
    }
}

// For typed frontend errors, use tagged serialization:
#[derive(Serialize)]
#[serde(tag = "kind", content = "message")]
#[serde(rename_all = "camelCase")]
pub enum TypedError {
    Io(String),
    Validation(String),
    NotFound(String),
}
// Produces: { kind: 'io' | 'validation' | 'notFound', message: string }

State Management (std::Mutex vs tokio::Mutex):

// SYNC commands: Use std::sync::Mutex
use std::sync::Mutex;

#[tauri::command]
fn increment(state: State<'_, Mutex<AppState>>) -> u32 {
    let mut state = state.lock().unwrap();
    state.counter += 1;
    state.counter
}

// ASYNC commands: Use tokio::sync::Mutex (avoids blocking!)
use tokio::sync::Mutex;

#[tauri::command]
async fn async_increment(state: State<'_, Mutex<AppState>>) -> Result<u32, ()> {
    let mut state = state.lock().await;  // .await not .unwrap()!
    state.counter += 1;
    Ok(state.counter)
}

// CRITICAL: Async commands with borrowed args need Result return type
// ❌ Won't compile
async fn cmd(state: State<'_, AppState>) { }

// ✅ Correct pattern
async fn cmd(state: State<'_, AppState>) -> Result<(), ()> { Ok(()) }

Security: Path Traversal Prevention:

#[tauri::command]
async fn read_file(path: String, app: AppHandle) -> Result<String, String> {
    let path = std::path::Path::new(&path);

    // Prevent path traversal attacks
    if path.components().any(|c| matches!(c, std::path::Component::ParentDir)) {
        return Err("Invalid path: directory traversal not allowed".into());
    }

    // Validate against allowed base directory
    let base = app.path().app_data_dir().unwrap();
    let full_path = base.join(&path);
    let canonical = full_path.canonicalize()
        .map_err(|e| format!("Invalid path: {}", e))?;

    if !canonical.starts_with(&base) {
        return Err("Access denied: path outside allowed scope".into());
    }

    std::fs::read_to_string(canonical).map_err(|e| e.to_string())
}

Async Performance (spawn_blocking for CPU-intensive):

// CPU-intensive work should use spawn_blocking
#[tauri::command]
async fn heavy_computation(data: Vec<u8>) -> Result<Vec<u8>, String> {
    tokio::task::spawn_blocking(move || {
        process_heavy_data(data)  // Runs on blocking thread pool
    }).await.map_err(|e| e.to_string())
}

// I/O work uses regular async
#[tauri::command]
async fn fetch_data(url: String) -> Result<Data, String> {
    reqwest::get(&url).await
        .map_err(|e| e.to_string())?
        .json().await
        .map_err(|e| e.to_string())
}

Extension Traits for AppHandle:

pub trait AppHandleExt {
    fn get_database(&self) -> Arc<Database>;
    fn emit_global(&self, event: &str, payload: impl Serialize);
}

impl AppHandleExt for tauri::AppHandle {
    fn get_database(&self) -> Arc<Database> {
        self.state::<Arc<Database>>().inner().clone()
    }

    fn emit_global(&self, event: &str, payload: impl Serialize) {
        self.emit(event, payload).unwrap();
    }
}

// Usage in commands:
#[tauri::command]
async fn get_pods(app: AppHandle) -> Result<Vec<Pod>, AppError> {
    let db = app.get_database();
    db.query_pods().await
}

Events for Real-time Updates (Backend → Frontend):

use tauri::{AppHandle, Emitter};

#[derive(Clone, Serialize)]
struct ProgressUpdate { percent: u32, status: String }

#[tauri::command]
async fn long_operation(app: AppHandle) -> Result<(), String> {
    for i in 0..=100 {
        app.emit("progress", ProgressUpdate {
            percent: i,
            status: format!("Processing {}%", i)
        }).unwrap();
        tokio::time::sleep(Duration::from_millis(50)).await;
    }
    Ok(())
}
// Frontend: Always cleanup listeners!
import { listen } from '@tauri-apps/api/event';

const unlisten = await listen<ProgressUpdate>('progress', (event) => {
  console.log(`Progress: ${event.payload.percent}%`);
});

// Cleanup on unmount
onCleanup(() => unlisten());

Tauri 2.0 Capability-Based Security:

// src-tauri/capabilities/default.json
{
  "$schema": "../gen/schemas/desktop-schema.json",
  "identifier": "main-capability",
  "windows": ["main"],
  "permissions": [
    "core:default",
    "fs:default",
    {
      "identifier": "fs:allow-read",
      "allow": [{ "path": "$APPDATA/*" }],
      "deny": [{ "path": "$HOME/.ssh/*" }]
    }
  ]
}

Release Build Optimization:

# Cargo.toml
[profile.release]
lto = true              # Link-time optimization
codegen-units = 1       # Better optimization
opt-level = "s"         # Optimize for size
panic = "abort"         # Smaller binary
strip = true            # Remove debug symbols

Channels for High-Throughput Streaming (Alternative to Events):

use tauri::ipc::Channel;

#[derive(Clone, Serialize)]
#[serde(rename_all = "camelCase", tag = "event", content = "data")]
enum DownloadEvent<'a> {
    Started { url: &'a str, size: u64 },
    Progress { percent: u8, downloaded: u64 },
    Finished,
}

#[tauri::command]
fn download(url: String, on_progress: Channel<DownloadEvent>) {
    on_progress.send(DownloadEvent::Started { url: &url, size: 1024 }).unwrap();
    // ... streaming data
    for i in 0..=100 {
        on_progress.send(DownloadEvent::Progress { percent: i, downloaded: i as u64 * 10 }).unwrap();
    }
    on_progress.send(DownloadEvent::Finished).unwrap();
}
// Frontend: Channel usage
await invoke('download', {
  url: 'https://example.com/file',
  onProgress: new Channel<DownloadEvent>((event) => {
    if (event.event === 'progress') {
      console.log(`Downloaded: ${event.data.percent}%`);
    }
  })
});

Multi-Window Security Isolation:

// capabilities/admin.json - More privileges
{
  "identifier": "admin-capability",
  "windows": ["admin-*"],
  "permissions": ["fs:default", "fs:allow-write", "shell:allow-execute"]
}

// capabilities/viewer.json - Read-only
{
  "identifier": "viewer-capability",
  "windows": ["viewer-*"],
  "permissions": ["fs:allow-read"]
}

Content Security Policy (CSP):

// tauri.conf.json
{
  "app": {
    "security": {
      "csp": {
        "default-src": "'self' customprotocol: asset:",
        "connect-src": "ipc: http://ipc.localhost",
        "script-src": "'self'",
        "style-src": "'unsafe-inline' 'self'"
      }
    }
  }
}

Security Hardening Checklist:

  • Enable strict CSP with default-src 'self'
  • Configure per-window capabilities with minimum permissions
  • Define scopes to restrict file system access
  • Validate ALL command inputs in Rust (frontend is untrusted!)
  • Run cargo audit and npm audit regularly
  • Never load remote/untrusted content
  • Sign all release binaries
  • Use tokio::sync::Mutex for async commands (not std::sync)

Splashscreen Startup Optimization:

tauri::Builder::default()
    .setup(|app| {
        let splashscreen = app.get_webview_window("splashscreen").unwrap();
        let main_window = app.get_webview_window("main").unwrap();

        tauri::async_runtime::spawn(async move {
            // Heavy initialization here (doesn't block UI)
            initialize_database().await;
            load_config().await;

            splashscreen.close().unwrap();
            main_window.show().unwrap();
        });
        Ok(())
    })

Mobile Support (lib.rs Entry Point):

// src-tauri/src/lib.rs
#[cfg_attr(mobile, tauri::mobile_entry_point)]
pub fn run() {
    tauri::Builder::default()
        .invoke_handler(tauri::generate_handler![...])
        .run(tauri::generate_context!())
        .expect("error running app");
}

// src-tauri/src/main.rs (minimal)
fn main() {
    kubeli_lib::run();
}

Testing: Rust Commands with Mock Runtime:

#[cfg(test)]
mod tests {
    use tauri::test::{mock_builder, mock_context, noop_assets};

    fn create_app() -> tauri::App<tauri::test::MockRuntime> {
        mock_builder()
            .invoke_handler(tauri::generate_handler![super::greet])
            .build(mock_context(noop_assets()))
            .expect("failed to build app")
    }

    #[test]
    fn test_greet() {
        let _app = create_app();
        let result = super::greet("World");
        assert_eq!(result, "Hello, World!");
    }
}
# Enable test feature in Cargo.toml
[dependencies]
tauri = { version = "2.0", features = ["test"] }

Testing: Frontend IPC Mocking (Vitest):

import { mockIPC, clearMocks } from '@tauri-apps/api/mocks';
import { invoke } from '@tauri-apps/api/core';

afterEach(() => clearMocks());

test('invoke add command', async () => {
  mockIPC((cmd, args) => {
    if (cmd === 'add') return (args as { a: number; b: number }).a + args.b;
  });

  const result = await invoke('add', { a: 12, b: 15 });
  expect(result).toBe(27);
});

Code Quality: Clippy Configuration:

# Cargo.toml
[lints.clippy]
pedantic = { level = "warn", priority = -1 }
unwrap_used = "deny"          # Force proper error handling
expect_used = "warn"
module_name_repetitions = "allow"

Code Quality: rustfmt.toml:

edition = "2021"
max_width = 100
imports_granularity = "Module"
group_imports = "StdExternalCrate"
wrap_comments = true

Workspace Dependency Management:

# Root Cargo.toml
[workspace.dependencies]
tauri = { version = "2.0", features = [] }
serde = { version = "1.0", features = ["derive"] }
tokio = { version = "1", features = ["full"] }

# Member Cargo.toml - inherit from workspace
[dependencies]
tauri.workspace = true
serde.workspace = true

React / TypeScript Patterns

Component Cohesion (Single Responsibility):

// BEFORE: Component does too much
function PodManager() {
  const [pods, setPods] = useState([]);
  const [filter, setFilter] = useState('');
  const [sortBy, setSortBy] = useState('name');
  const [selectedPod, setSelectedPod] = useState(null);
  const [isDeleting, setIsDeleting] = useState(false);
  const [showLogs, setShowLogs] = useState(false);
  // ... 200 lines of mixed concerns

  return (
    <div>
      <FilterBar ... />
      <PodList ... />
      <PodDetails ... />
      <DeleteConfirmation ... />
      <LogViewer ... />
    </div>
  );
}

// AFTER: Separated concerns
function PodManager() {
  return (
    <PodFilterProvider>
      <div>
        <PodFilterBar />
        <PodListWithSelection />
        <PodDetailsPanel />
      </div>
    </PodFilterProvider>
  );
}
// Each sub-component manages its own state or uses shared store

Props Interface Simplification:

// BEFORE: Too many props (shallow module)
interface PodCardProps {
  name: string;
  namespace: string;
  status: string;
  createdAt: Date;
  labels: Record<string, string>;
  onSelect: () => void;
  onDelete: () => void;
  onViewLogs: () => void;
  onRestart: () => void;
  isSelected: boolean;
  showActions: boolean;
}

// AFTER: Deep module with simple interface
interface PodCardProps {
  pod: Pod;
  onAction?: (action: PodAction) => void;
}

type PodAction =
  | { type: 'select' }
  | { type: 'delete' }
  | { type: 'viewLogs' }
  | { type: 'restart' };

Custom Hooks for Reusable Logic:

// BEFORE: Duplicated logic in components
function PodList() {
  const [data, setData] = useState([]);
  const [loading, setLoading] = useState(false);
  const [error, setError] = useState(null);

  useEffect(() => {
    setLoading(true);
    invoke('get_pods', { namespace })
      .then(setData)
      .catch(setError)
      .finally(() => setLoading(false));
  }, [namespace]);
  // ...
}

// AFTER: Reusable hook
function useTauriQuery<T>(command: string, args: Record<string, unknown>) {
  const [data, setData] = useState<T | null>(null);
  const [loading, setLoading] = useState(false);
  const [error, setError] = useState<Error | null>(null);

  useEffect(() => {
    setLoading(true);
    invoke<T>(command, args)
      .then(setData)
      .catch(setError)
      .finally(() => setLoading(false));
  }, [command, JSON.stringify(args)]);

  return { data, loading, error };
}

// Usage
function PodList({ namespace }: Props) {
  const { data: pods, loading, error } = useTauriQuery<Pod[]>('get_pods', { namespace });
  // ...
}

Phase 5: Refactoring Workflow

Step-by-Step Process

  1. Analyze (5-10 min)
    • Run /software-design-review on target code
    • Identify top 3 complexity issues
    • Choose ONE to fix first
  2. Design (5 min)
    • Consider 2-3 alternative approaches
    • Pick the one with simplest interface
    • Write the interface comment FIRST
  3. Test (before coding)
    • Ensure tests exist
    • If not, write characterization tests
    • Run tests to confirm green
  4. Refactor (small steps)
    • Make ONE change at a time
    • Run tests after each change
    • Commit after each working step
  5. Review (after)
    • Does the code look like it was designed this way?
    • Is the interface simpler?
    • Did we improve or just move complexity?

Commit Strategy

# Small, atomic commits
git commit -m "refactor(pods): extract PodCard props into Pod type"
git commit -m "refactor(pods): create usePod hook for selective access"
git commit -m "refactor(pods): move pod filtering to dedicated hook"

# NOT one giant commit
git commit -m "refactor: improve pod management"  # BAD: too vague

Phase 6: Prioritization Matrix

Rate each issue and fix highest impact first:

IssueComplexity ReductionEffortRiskPriority
High impact, Low effort, Low risk⬆️⬆️⬆️⬇️⬇️P0 - Do First
High impact, Medium effort⬆️⬆️⬆️➡️➡️P1
Medium impact, Low effort⬆️⬆️⬇️⬇️P2
Low impact OR High risk⬆️Any⬆️P3 - Later

Your Output Format

1. Analysis Summary

Target: [file/directory]
Current Complexity: [Low/Medium/High]
Top Issues:
1. [Issue + Principle violated]
2. [Issue + Principle violated]
3. [Issue + Principle violated]

2. Refactoring Plan

Priority | Issue | Refactoring | Estimated Changes
---------|-------|-------------|------------------
P0       | ...   | ...         | ~X files, ~Y lines
P1       | ...   | ...         | ...

3. Step-by-Step Execution

For each P0/P1 item:

  1. What to change
  2. Expected interface (comment first)
  3. Test requirements
  4. Implementation steps

4. Safety Notes

  • Tests to add/verify
  • Potential breaking changes
  • Rollback plan if needed

Sources & References

Books

  • John Ousterhout: "A Philosophy of Software Design" (15 Principles)
  • Robert C. Martin: "Clean Code" (Smells & Heuristics)
  • Martin Fowler: "Refactoring" (Refactoring Catalog)

Web Resources

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.