playbooks

home / skills / agykit / agykit / codebase_safety

codebase_safety skill

/.agent/skills/codebase_safety

This skill guides safe navigation and modification of an existing codebase, helping onboarding, impact analysis, and risk-aware changes across languages.

npx playbooks add skill agykit/agykit --skill codebase_safety

Review the files below or copy the command above to add this skill to your agents.

Files (1)
SKILL.md
3.4 KB
---
name: Codebase Safety & Exploration
description: "Guide for safely navigating and modifying an existing codebase. Use this skill when: (1) Onboarding to a new project or context, (2) Planning complex changes that might have side effects, (3) Ensuring modifications don't break existing functionality across different languages and frameworks."
---

# Codebase Safety & Exploration

This skill provides a systematic approach to understanding an existing project and ensuring that changes are safe and side-effect-free.

## 1. Project Onboarding (Context Acquisition)

Before making changes, establish a mental map of the project.

### 1.1. Map the Structure
-   **List Files**: Run `list_dir` on the root directory.
-   **Read Documentation**: Locate and read high-level docs like `README.md`, `CONTRIBUTING.md`, `AGENTS.md`, or architecture design docs.

### 1.2. Identify Tech Stack & Scripts
Identify the build system and available scripts by reading the manifest file specific to the language:
-   **JavaScript/TypeScript**: `package.json` (Look for `scripts`, `dependencies`)
-   **Python**: `pyproject.toml`, `requirements.txt`, or `setup.py`
-   **Go**: `go.mod`, `Makefile`
-   **Rust**: `Cargo.toml`
-   **Java/Kotlin**: `pom.xml` (Maven) or `build.gradle` (Gradle)

*Goal*: specific commands for **building**, **testing**, and **linting**.

### 1.3. Check Conventions
-   **Path Aliases**: Check configuration files (e.g., `tsconfig.json`, `webpack.config.js`) to understand import aliases (e.g., `@/components`).
-   **Style Guide**: Check linter configs (`.eslintrc`, `.pylintrc`) if available.

## 2. Impact Analysis (Pre-Edit)

Perform this analysis *before* every significant edit (`TargetFile`).

### 2.1. Identify Artifacts
Determine what the `TargetFile` exports or defines (Classes, Functions, Constants, Components).

### 2.2. Find References (Usage Scan)
Use `grep_search` to find where these artifacts are used.
-   **Import Search**: `grep_search(SearchPath=".", Query="import .* from .*TargetFileName")` (Adjust syntax for language, e.g., `use .*::TargetModule` for Rust).
-   **Symbol Search**: Search for the specific function or class name.

### 2.3. Risk Classification
-   **Low Risk**: Used in strictly one location (e.g., a private helper or leaf component).
-   **High Risk**: Used in multiple places, shared utilities, core business logic, or public APIs.
    -   *Strategy*: For High Risk items, prefer **extending** (optional parameters/props) over **changing** existing behavior. Consider creating a new version (v2) if the change is breaking.

## 3. Safe Modification Workflow

### 3.1. Pre-Check (Baseline)
Run the project's linter or test suite for the relevant area to ensure a clean state before you touch it.
-   *Example*: `npm run lint` or `pytest specific/test_file.py`

### 3.2. Apply Changes
Perform your edits using the appropriate file manipulation tools.

### 3.3. Post-Check (Verification)
1.  **Static Analysis**: Run linters/type-checkers again.
2.  **Logic Verification**:
    -   If tests exist, run them: `npm test -- specific/file` or `go test ./package/...`
    -   If no tests exist, consider adding a basic unit test if feasible and allowed.

## 4. Final Handoff

When reporting back to the user:
-   **Summary**: List modified files.
-   **Impact Radius**: Explicitly state which other parts of the system might be affected based on your Impact Analysis.
-   **Verification**: Confirm that lint/type-check passed.

Overview

This skill guides safe navigation and modification of an existing codebase to minimize regressions and side effects. It provides a repeatable onboarding checklist, impact analysis steps before edits, a safe modification workflow, and a clear handoff template. Use it to build confidence when touching unfamiliar or critical code across languages and frameworks.

How this skill works

Start by mapping project structure and locating build/test/lint commands from manifests and docs. For any target file, enumerate exported artifacts, search for usages across the repo, and classify risk based on footprint. Make edits only after baseline checks, then rerun static analysis and targeted tests and report a concise impact summary.

When to use it

  • Onboarding to a new project and needing a reliable way to build situational awareness.
  • Planning changes that could affect multiple modules, shared utilities, or public APIs.
  • Modifying cross-language repositories where import conventions or manifest files differ.
  • Before refactors, to decide whether to extend behavior or introduce a v2 API.
  • When there are limited or no tests and you must decide whether to add basic verification.

Best practices

  • Always run linter/type-check and the relevant test subset before making changes.
  • Identify exports and grep for all references to measure change impact and scope.
  • Classify edits as low- or high-risk; prefer extending behavior or creating v2 for breaking changes.
  • If no tests exist for the changed area, add a minimal unit/integration test when feasible.
  • Document modified files, impact radius, and verification commands in your handoff.

Example use cases

  • Changing a shared utility function used by backend jobs and frontend code; scan imports and run both server and client tests.
  • Onboarding to a polyglot repo: locate package.json, pyproject.toml, go.mod, or Cargo.toml to discover build/test commands.
  • Planning a UI prop change: search for component consumers, decide to add an optional prop instead of altering existing behavior.
  • Preparing a safe refactor of core business logic: create a new implementation, run targeted tests, and keep the original until verification passes.
  • Making a small fix in a leaf helper: confirm low-risk by finding single usage, run linter and the specific test file.

FAQ

What if the repo has no tests?

Run linters and type-checkers; search for usages to limit impact and add a minimal test for the changed area when practical.

How do I handle ambiguous imports or path aliases?

Inspect config files (tsconfig.json, webpack.config.js, or equivalent) to resolve aliases and then grep using resolved paths or symbols.