{
  "schemaVersion": "1.0",
  "item": {
    "slug": "ai-codebase-deep-modules",
    "name": "Deep modules for agent-native codebases",
    "source": "tencent",
    "type": "skill",
    "category": "AI 智能",
    "sourceUrl": "https://clawhub.ai/tristanmanchester/ai-codebase-deep-modules",
    "canonicalUrl": "https://clawhub.ai/tristanmanchester/ai-codebase-deep-modules",
    "targetPlatform": "OpenClaw"
  },
  "install": {
    "downloadMode": "redirect",
    "downloadUrl": "/downloads/ai-codebase-deep-modules",
    "sourceDownloadUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=ai-codebase-deep-modules",
    "sourcePlatform": "tencent",
    "targetPlatform": "OpenClaw",
    "installMethod": "Manual import",
    "extraction": "Extract archive",
    "prerequisites": [
      "OpenClaw"
    ],
    "packageFormat": "ZIP package",
    "includedAssets": [
      "references/module-templates.md",
      "references/testing-and-feedback.md",
      "references/boundary-enforcement.md",
      "references/prompts.md",
      "scripts/scaffold_deep_module.py",
      "SKILL.md"
    ],
    "primaryDoc": "SKILL.md",
    "quickSetup": [
      "Download the package from Yavira.",
      "Extract the archive and review SKILL.md first.",
      "Import or place the package into your OpenClaw setup."
    ],
    "agentAssist": {
      "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.",
      "steps": [
        "Download the package from Yavira.",
        "Extract it into a folder your agent can access.",
        "Paste one of the prompts below and point your agent at the extracted folder."
      ],
      "prompts": [
        {
          "label": "New install",
          "body": "I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Tell me what you changed and call out any manual steps you could not complete."
        },
        {
          "label": "Upgrade existing",
          "body": "I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Summarize what changed and any follow-up checks I should run."
        }
      ]
    },
    "sourceHealth": {
      "source": "tencent",
      "status": "healthy",
      "reason": "direct_download_ok",
      "recommendedAction": "download",
      "checkedAt": "2026-04-30T16:55:25.780Z",
      "expiresAt": "2026-05-07T16:55:25.780Z",
      "httpStatus": 200,
      "finalUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=network",
      "contentType": "application/zip",
      "probeMethod": "head",
      "details": {
        "probeUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=network",
        "contentDisposition": "attachment; filename=\"network-1.0.0.zip\"",
        "redirectLocation": null,
        "bodySnippet": null
      },
      "scope": "source",
      "summary": "Source download looks usable.",
      "detail": "Yavira can redirect you to the upstream package for this source.",
      "primaryActionLabel": "Download for OpenClaw",
      "primaryActionHref": "/downloads/ai-codebase-deep-modules"
    },
    "validation": {
      "installChecklist": [
        "Use the Yavira download entry.",
        "Review SKILL.md after the package is downloaded.",
        "Confirm the extracted package contains the expected setup assets."
      ],
      "postInstallChecks": [
        "Confirm the extracted package includes the expected docs or setup files.",
        "Validate the skill or prompts are available in your target agent workspace.",
        "Capture any manual follow-up steps the agent could not complete."
      ]
    },
    "downloadPageUrl": "https://openagent3.xyz/downloads/ai-codebase-deep-modules",
    "agentPageUrl": "https://openagent3.xyz/skills/ai-codebase-deep-modules/agent",
    "manifestUrl": "https://openagent3.xyz/skills/ai-codebase-deep-modules/agent.json",
    "briefUrl": "https://openagent3.xyz/skills/ai-codebase-deep-modules/agent.md"
  },
  "agentAssist": {
    "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.",
    "steps": [
      "Download the package from Yavira.",
      "Extract it into a folder your agent can access.",
      "Paste one of the prompts below and point your agent at the extracted folder."
    ],
    "prompts": [
      {
        "label": "New install",
        "body": "I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Tell me what you changed and call out any manual steps you could not complete."
      },
      {
        "label": "Upgrade existing",
        "body": "I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Summarize what changed and any follow-up checks I should run."
      }
    ]
  },
  "documentation": {
    "source": "clawhub",
    "primaryDoc": "SKILL.md",
    "sections": [
      {
        "title": "AI Codebase Deep Modules",
        "body": "Turn “a web of shallow, cross-importing files” into a codebase that is easy for AI (and humans) to navigate, change, and test.\n\nThis skill is built around four ideas:\n\nThe codebase matters more than the prompt. AI struggles when feedback is slow, structure is unclear, and dependencies are tangled.\nMatch the filesystem to the mental model. Group code the way you think about it (features/domains/services), not as a grab-bag of utilities.\nPrefer deep modules. Lots of implementation behind a small, well-designed public interface.\nTreat deep modules as greyboxes. Lock behaviour with tests at the boundary; internal code becomes replaceable."
      },
      {
        "title": "When to use this skill",
        "body": "Use this skill when the user wants any of the following:\n\nRefactor an existing repo to be more navigable and safer for AI-assisted coding\nIntroduce/strengthen module boundaries, reduce coupling, or eliminate “spaghetti imports”\nRestructure the repo by feature/domain (a “map you hold in your head” reflected on disk)\nDefine service/module interfaces, public APIs, and “only import from here” rules\nBuild fast feedback loops (tests, typecheck, lint) so AI can verify changes quickly\nPlan a refactor with incremental steps, acceptance criteria, and tests\n\nDo not use this skill for:\n\nOne-off debugging of an isolated error (use normal debugging / code review)\nPurely stylistic refactors with no boundary or testing implications\nWriting greenfield code where the user already has a clear modular architecture (unless they want a module template)"
      },
      {
        "title": "Inputs this skill expects (minimal)",
        "body": "If available, ask for or infer:\n\nLanguage/runtime (TS/JS, Python, Go, Java/Kotlin, etc.)\nHow to run the fastest meaningful check (unit tests, typecheck, lint, build)\nThe top 3–7 “chunks” of product behaviour (domains/features/services)\nAny hard constraints (monorepo tooling, existing packages, deployment boundaries)\n\nIf the user hasn’t provided this, do not stall. Make best-effort guesses by inspecting:\n\npackage.json, pyproject.toml, go.mod, pom.xml, build.gradle, Makefile, justfile\nsrc/, app/, packages/, services/, modules/\nexisting test folders and CI configs"
      },
      {
        "title": "Step 0 — Establish the feedback loop (non-negotiable)",
        "body": "Goal: ensure there is a fast “did it work?” loop before and during refactors.\n\nIdentify the quickest command that provides signal:\n\nTypecheck: tsc -p tsconfig.json\nUnit tests: npm test, pytest -q, go test ./...\nLint: eslint ., ruff check, golangci-lint run\n\n\nPrefer a single “verify” entrypoint:\n\nmake verify, just verify, npm run verify, ./scripts/verify.sh\n\n\nIf tests are missing, propose the smallest viable starting point:\n\nSmoke tests for core flows\nContract tests for the boundaries you’re about to introduce\n\n\nIf the loop is slow, propose speed-ups before large refactors:\n\nRun only impacted packages\nSplit unit vs integration tests\nCache dependencies in CI\n\nDeliverable: a short “Feedback loop” section with the exact commands and expected outputs."
      },
      {
        "title": "Step 1 — Reconstruct the mental map of the codebase",
        "body": "Goal: identify the natural groupings that already exist in the product.\n\nList the product domains/features (aim for 3–10):\n\ne.g. auth, billing, thumbnail-editor, video-editor, cms-forms\n\n\nFor each domain, identify:\n\nentrypoints (routes/controllers/handlers)\ndata boundaries (models/schemas)\nexternal dependencies (APIs, DB, queues)\n\n\nCapture the current pain:\n\n“Where do people get lost?”\n“What breaks when we change X?”\n“Where are imports crossing domains?”\n\nDeliverable: a Module Map (table) with: domain, responsibilities, key files, current coupling risks."
      },
      {
        "title": "Step 2 — Design deep modules (few, chunky, stable interfaces)",
        "body": "Goal: reduce the number of things the agent must keep in working memory.\n\nFor each domain/module candidate:\n\nDefine the public interface (small surface area):\n\nfunctions/classes/commands exposed\npublic types/data contracts\nerror/edge-case semantics\n\n\nDefine what is explicitly internal:\n\nhelper functions, adapters, DB queries, parsing, etc.\n\n\nDecide the dependency direction:\n\nPrefer: domain → shared primitives\nAvoid: domain ↔ domain cross-imports\n\n\nKeep the interface boring and predictable:\n\nstable names\nminimal parameters\nexplicit return types / result objects\n\nDeliverable: an Interface Spec for each deep module:\n\nPublic API (signatures)\nInvariants (pre/post conditions)\nExamples (happy path + one edge case)\n\nSee: references/module-templates.md"
      },
      {
        "title": "Step 3 — Align the filesystem to the map (progressive disclosure)",
        "body": "Goal: make it obvious where to look.\n\nDefault rule: outside code imports only from a module’s public entrypoint.\n\nRecommended structure (adapt per language):\n\nsrc/<module>/\n\nindex.* (public exports)\ntypes.* (public types)\ninternal/ (implementation details; not imported from outside)\n__tests__/ or tests/ (contract tests for the public API)\n\nIf the repo uses packages, prefer packages/<module>/ with explicit exports.\n\nDeliverable: a “Move plan” listing:\n\ndirectories to create\nfiles to move\nimport paths to update\ntemporary compatibility shims (if needed)"
      },
      {
        "title": "Step 4 — Make modules greyboxes with boundary tests",
        "body": "Goal: you shouldn’t need to understand internals to trust behaviour.\n\nWrite/identify contract tests for each module’s public API:\n\nbehavioural checks\nkey error cases\nside effects (DB writes, events emitted) via fakes/spies\n\n\nKeep tests close to the interface:\n\ntreat internals as replaceable\n\n\nOnly add internal unit tests where:\n\nperformance-critical logic needs tight coverage\ntricky algorithms deserve direct tests\n\nDeliverable: test plan + initial contract test skeletons.\n\nSee: references/testing-and-feedback.md"
      },
      {
        "title": "Step 5 — Enforce boundaries (so the architecture stays true)",
        "body": "Goal: prevent the codebase from drifting back into a web.\n\nPick the lightest viable enforcement:\n\nConventions + code review (baseline)\nLint rules (TS/JS: no-restricted-imports, ESLint boundary plugins)\nArchitecture tests (assert “module A cannot import module B”)\nLanguage-level boundaries (Go internal/, Rust pub(crate), Java modules)\n\nDeliverable: an “Enforcement” section with the exact rules and where to configure them.\n\nSee: references/boundary-enforcement.md"
      },
      {
        "title": "Step 6 — Refactor incrementally (strangler pattern)",
        "body": "Goal: avoid giant-bang rewrites.\n\nSuggested sequence:\n\nCreate the new module folder and public interface (empty implementation).\nAdd contract tests (they will fail).\nAdd a thin adapter that wraps existing code (tests pass).\nMove internals gradually behind the interface:\n\nkeep exports stable\ndelete old entrypoints only once usage is migrated\n\n\nRepeat module-by-module.\n\nDeliverable: a stepwise refactor plan with checkpoints and rollback options."
      },
      {
        "title": "Output format (what to produce)",
        "body": "When this skill is activated, produce a structured plan using this outline:\n\nCurrent state summary (1–2 paragraphs)\nFast feedback loop (exact commands)\nModule Map (table)\nProposed deep modules (list + responsibilities)\nInterface specs (per module)\nFilesystem changes (move plan)\nBoundary enforcement (rules + tooling)\nTesting strategy (contract tests first)\nIncremental migration steps (with checkpoints)\n\nOptional: copy the template from assets/architecture-plan-template.md."
      },
      {
        "title": "Example 1 — Broad request",
        "body": "User says: “Make our TypeScript monorepo more AI-friendly. It’s hard to find things and tests are slow.”\n\nActions:\n\nIdentify verify loop (typecheck + unit tests) and how to run it per package.\nProduce a module map (3–7 modules).\nPropose deep modules with a clear public interface (index.ts, types.ts).\nRecommend boundary enforcement via ESLint no-restricted-imports.\nAdd contract tests for each module.\n\nResult: a concrete refactor plan and initial skeletons that can be executed incrementally."
      },
      {
        "title": "Example 2 — Specific boundary problem",
        "body": "User says: “Auth imports billing and billing imports auth. We keep breaking things.”\n\nActions:\n\nIdentify dependency cycle and why it exists (shared types? shared DB code?).\nExtract a deep module interface boundary:\n\nauth exports getCurrentUser(), requireAuth()\nbilling depends on those interfaces only (no deep imports)\n\n\nMove shared primitives into shared/ or platform/ module.\nAdd an architecture rule to prevent the cycle returning.\n\nResult: cycle removed, boundaries enforced, behaviour locked by tests."
      },
      {
        "title": "Skill feels too “high level”",
        "body": "Use the template and references to get concrete:\n\nreferences/module-templates.md\nreferences/prompts.md"
      },
      {
        "title": "Refactor is risky / unknown behaviour",
        "body": "Prioritise greybox contract tests first:\n\nfreeze behaviour at the public interface\nonly then move internals"
      },
      {
        "title": "Boundaries are hard to enforce in TS/JS",
        "body": "Start with lint rules and path conventions; add architecture tests if needed.\nSee: references/boundary-enforcement.md"
      }
    ],
    "body": "AI Codebase Deep Modules\n\nTurn “a web of shallow, cross-importing files” into a codebase that is easy for AI (and humans) to navigate, change, and test.\n\nThis skill is built around four ideas:\n\nThe codebase matters more than the prompt. AI struggles when feedback is slow, structure is unclear, and dependencies are tangled.\nMatch the filesystem to the mental model. Group code the way you think about it (features/domains/services), not as a grab-bag of utilities.\nPrefer deep modules. Lots of implementation behind a small, well-designed public interface.\nTreat deep modules as greyboxes. Lock behaviour with tests at the boundary; internal code becomes replaceable.\nWhen to use this skill\n\nUse this skill when the user wants any of the following:\n\nRefactor an existing repo to be more navigable and safer for AI-assisted coding\nIntroduce/strengthen module boundaries, reduce coupling, or eliminate “spaghetti imports”\nRestructure the repo by feature/domain (a “map you hold in your head” reflected on disk)\nDefine service/module interfaces, public APIs, and “only import from here” rules\nBuild fast feedback loops (tests, typecheck, lint) so AI can verify changes quickly\nPlan a refactor with incremental steps, acceptance criteria, and tests\n\nDo not use this skill for:\n\nOne-off debugging of an isolated error (use normal debugging / code review)\nPurely stylistic refactors with no boundary or testing implications\nWriting greenfield code where the user already has a clear modular architecture (unless they want a module template)\nInputs this skill expects (minimal)\n\nIf available, ask for or infer:\n\nLanguage/runtime (TS/JS, Python, Go, Java/Kotlin, etc.)\nHow to run the fastest meaningful check (unit tests, typecheck, lint, build)\nThe top 3–7 “chunks” of product behaviour (domains/features/services)\nAny hard constraints (monorepo tooling, existing packages, deployment boundaries)\n\nIf the user hasn’t provided this, do not stall. Make best-effort guesses by inspecting:\n\npackage.json, pyproject.toml, go.mod, pom.xml, build.gradle, Makefile, justfile\nsrc/, app/, packages/, services/, modules/\nexisting test folders and CI configs\nWorkflow\nStep 0 — Establish the feedback loop (non-negotiable)\n\nGoal: ensure there is a fast “did it work?” loop before and during refactors.\n\nIdentify the quickest command that provides signal:\nTypecheck: tsc -p tsconfig.json\nUnit tests: npm test, pytest -q, go test ./...\nLint: eslint ., ruff check, golangci-lint run\nPrefer a single “verify” entrypoint:\nmake verify, just verify, npm run verify, ./scripts/verify.sh\nIf tests are missing, propose the smallest viable starting point:\nSmoke tests for core flows\nContract tests for the boundaries you’re about to introduce\nIf the loop is slow, propose speed-ups before large refactors:\nRun only impacted packages\nSplit unit vs integration tests\nCache dependencies in CI\n\nDeliverable: a short “Feedback loop” section with the exact commands and expected outputs.\n\nStep 1 — Reconstruct the mental map of the codebase\n\nGoal: identify the natural groupings that already exist in the product.\n\nList the product domains/features (aim for 3–10):\ne.g. auth, billing, thumbnail-editor, video-editor, cms-forms\nFor each domain, identify:\nentrypoints (routes/controllers/handlers)\ndata boundaries (models/schemas)\nexternal dependencies (APIs, DB, queues)\nCapture the current pain:\n“Where do people get lost?”\n“What breaks when we change X?”\n“Where are imports crossing domains?”\n\nDeliverable: a Module Map (table) with: domain, responsibilities, key files, current coupling risks.\n\nStep 2 — Design deep modules (few, chunky, stable interfaces)\n\nGoal: reduce the number of things the agent must keep in working memory.\n\nFor each domain/module candidate:\n\nDefine the public interface (small surface area):\nfunctions/classes/commands exposed\npublic types/data contracts\nerror/edge-case semantics\nDefine what is explicitly internal:\nhelper functions, adapters, DB queries, parsing, etc.\nDecide the dependency direction:\nPrefer: domain → shared primitives\nAvoid: domain ↔ domain cross-imports\nKeep the interface boring and predictable:\nstable names\nminimal parameters\nexplicit return types / result objects\n\nDeliverable: an Interface Spec for each deep module:\n\nPublic API (signatures)\nInvariants (pre/post conditions)\nExamples (happy path + one edge case)\n\nSee: references/module-templates.md\n\nStep 3 — Align the filesystem to the map (progressive disclosure)\n\nGoal: make it obvious where to look.\n\nDefault rule: outside code imports only from a module’s public entrypoint.\n\nRecommended structure (adapt per language):\n\nsrc/<module>/\nindex.* (public exports)\ntypes.* (public types)\ninternal/ (implementation details; not imported from outside)\n__tests__/ or tests/ (contract tests for the public API)\n\nIf the repo uses packages, prefer packages/<module>/ with explicit exports.\n\nDeliverable: a “Move plan” listing:\n\ndirectories to create\nfiles to move\nimport paths to update\ntemporary compatibility shims (if needed)\nStep 4 — Make modules greyboxes with boundary tests\n\nGoal: you shouldn’t need to understand internals to trust behaviour.\n\nWrite/identify contract tests for each module’s public API:\nbehavioural checks\nkey error cases\nside effects (DB writes, events emitted) via fakes/spies\nKeep tests close to the interface:\ntreat internals as replaceable\nOnly add internal unit tests where:\nperformance-critical logic needs tight coverage\ntricky algorithms deserve direct tests\n\nDeliverable: test plan + initial contract test skeletons.\n\nSee: references/testing-and-feedback.md\n\nStep 5 — Enforce boundaries (so the architecture stays true)\n\nGoal: prevent the codebase from drifting back into a web.\n\nPick the lightest viable enforcement:\n\nConventions + code review (baseline)\nLint rules (TS/JS: no-restricted-imports, ESLint boundary plugins)\nArchitecture tests (assert “module A cannot import module B”)\nLanguage-level boundaries (Go internal/, Rust pub(crate), Java modules)\n\nDeliverable: an “Enforcement” section with the exact rules and where to configure them.\n\nSee: references/boundary-enforcement.md\n\nStep 6 — Refactor incrementally (strangler pattern)\n\nGoal: avoid giant-bang rewrites.\n\nSuggested sequence:\n\nCreate the new module folder and public interface (empty implementation).\nAdd contract tests (they will fail).\nAdd a thin adapter that wraps existing code (tests pass).\nMove internals gradually behind the interface:\nkeep exports stable\ndelete old entrypoints only once usage is migrated\nRepeat module-by-module.\n\nDeliverable: a stepwise refactor plan with checkpoints and rollback options.\n\nOutput format (what to produce)\n\nWhen this skill is activated, produce a structured plan using this outline:\n\nCurrent state summary (1–2 paragraphs)\nFast feedback loop (exact commands)\nModule Map (table)\nProposed deep modules (list + responsibilities)\nInterface specs (per module)\nFilesystem changes (move plan)\nBoundary enforcement (rules + tooling)\nTesting strategy (contract tests first)\nIncremental migration steps (with checkpoints)\n\nOptional: copy the template from assets/architecture-plan-template.md.\n\nExamples\nExample 1 — Broad request\n\nUser says: “Make our TypeScript monorepo more AI-friendly. It’s hard to find things and tests are slow.”\n\nActions:\n\nIdentify verify loop (typecheck + unit tests) and how to run it per package.\nProduce a module map (3–7 modules).\nPropose deep modules with a clear public interface (index.ts, types.ts).\nRecommend boundary enforcement via ESLint no-restricted-imports.\nAdd contract tests for each module.\n\nResult: a concrete refactor plan and initial skeletons that can be executed incrementally.\n\nExample 2 — Specific boundary problem\n\nUser says: “Auth imports billing and billing imports auth. We keep breaking things.”\n\nActions:\n\nIdentify dependency cycle and why it exists (shared types? shared DB code?).\nExtract a deep module interface boundary:\nauth exports getCurrentUser(), requireAuth()\nbilling depends on those interfaces only (no deep imports)\nMove shared primitives into shared/ or platform/ module.\nAdd an architecture rule to prevent the cycle returning.\n\nResult: cycle removed, boundaries enforced, behaviour locked by tests.\n\nTroubleshooting\nSkill feels too “high level”\n\nUse the template and references to get concrete:\n\nreferences/module-templates.md\nreferences/prompts.md\nRefactor is risky / unknown behaviour\n\nPrioritise greybox contract tests first:\n\nfreeze behaviour at the public interface\nonly then move internals\nBoundaries are hard to enforce in TS/JS\n\nStart with lint rules and path conventions; add architecture tests if needed. See: references/boundary-enforcement.md"
  },
  "trust": {
    "sourceLabel": "tencent",
    "provenanceUrl": "https://clawhub.ai/tristanmanchester/ai-codebase-deep-modules",
    "publisherUrl": "https://clawhub.ai/tristanmanchester/ai-codebase-deep-modules",
    "owner": "tristanmanchester",
    "version": "1.0.0",
    "license": null,
    "verificationStatus": "Indexed source record"
  },
  "links": {
    "detailUrl": "https://openagent3.xyz/skills/ai-codebase-deep-modules",
    "downloadUrl": "https://openagent3.xyz/downloads/ai-codebase-deep-modules",
    "agentUrl": "https://openagent3.xyz/skills/ai-codebase-deep-modules/agent",
    "manifestUrl": "https://openagent3.xyz/skills/ai-codebase-deep-modules/agent.json",
    "briefUrl": "https://openagent3.xyz/skills/ai-codebase-deep-modules/agent.md"
  }
}