modular-code-guard

Lightweight architecture guardrails for AI coding agents

Prevent massive files. Keep projects modular. Stay out of the way.

Instruction-only skills for Claude Code and Codex that help agents plan file structure before they write or refactor code.

English · Español

Installation · Usage · Examples · Philosophy

---

AI coding agents are great at shipping code, but they often create massive, hard-to-maintain files. modular-code-guard is a lightweight skill for Claude Code and Codex that nudges agents to plan file structure, split responsibilities, and keep projects maintainable.

If this helps your AI coding workflow, star the repo so other developers can find it.

github.com/anthonystepvoy/modular-code-guard

What is modular-code-guard?

modular-code-guard is an instruction-only architecture guardrail for AI coding agents. It helps agents decide where code should live before they write or refactor it.

It encourages practical separation across components, hooks, services, modules, types, schemas, utils, MCP tools, and feature folders without imposing a heavy workflow or a fixed architecture.

It is designed for teams and solo developers who want AI agents to keep momentum without turning every feature into a giant page, route, screen, or service file.

Why this exists

AI agents often finish tasks by putting everything into one file: UI, state, API calls, validation, helpers, business logic, MCP tooling, and rendering. That can work for a demo, but it quickly creates files that are difficult to review, test, and safely change.

This skill exists to add a small checkpoint before coding: plan the file structure, follow the existing project conventions, and avoid turning routes, pages, screens, or services into catch-all files.

What it prevents

• 1000 to 3000 line files created during feature work.
• Page or route files containing all feature logic.
• API calls embedded in JSX-heavy components.
• Validation schemas hidden inside UI files.
• Business logic buried in event handlers.
• Duplicated types and interfaces.
• MCP server, client, and tool logic mixed directly into UI components.
• Refactors that rewrite large files from scratch and accidentally change behavior.

What it does not do

• It is not Superpowers.
• It is not a full development methodology.
• It is not an enterprise framework.
• It is not a forced folder structure.
• It is not an automatic refactoring engine.
• It does not guarantee perfect architecture.

It is a practical guardrail that helps agents avoid obvious maintainability problems.

Supported agents

• Codex Agent Skills
• Claude Code Skills

Both skill files contain the same core guidance, with agent-specific wording where useful.

Installation

Clone or copy the files from this repository:

git clone https://github.com/anthonystepvoy/modular-code-guard.git

For Codex:

Copy .agents/skills/modular-code-guard/SKILL.md into your repo at:
.agents/skills/modular-code-guard/SKILL.md

For Claude Code:

Copy .claude/skills/modular-code-guard/SKILL.md into your repo at:
.claude/skills/modular-code-guard/SKILL.md

You can also copy these templates into your projects if you want the rules to apply as persistent project guidance:

templates/AGENTS.md
templates/CLAUDE.md

Quick start

1. Copy the skill file for your agent into your project.
2. Ask your agent to use modular-code-guard before non-trivial feature work or refactors.
3. Let the agent produce a short structure plan.
4. Review the proposed files before it writes code.
5. Run the project validation command after the change.

Usage

Ask your agent to use the skill when creating, modifying, or refactoring non-trivial code. The agent should inspect the existing project structure, produce a short structure plan when needed, then make focused changes.

For small typo fixes, copy changes, or minimal bug fixes, the skill should stay out of the way.

Example prompts

Use modular-code-guard while building this feature.

Before coding, apply modular-code-guard and propose the file structure.

Refactor this 2000-line file using modular-code-guard. Preserve behavior.

Audit this repo for files that violate modular-code-guard principles.

Recommended file organization

modular-code-guard adapts to the existing project structure first. When no clear structure exists, these concepts help decide where code belongs.

Component: A piece of UI. Usually answers: what appears on screen?

Module: A feature or domain folder that groups related code. Usually answers: what part of the system does this belong to?

Hook: Reusable React state or behavior logic.

Service: External communication or integration logic, such as API calls, database access, SDK calls, auth clients, or backend requests.

Utility: Pure reusable helper functions with no UI and no side effects.

Schema: Validation contracts, usually with Zod, Yup, Valibot, or similar.

Type: TypeScript interfaces, types, DTOs, enums, and shared contracts.

MCP tool: A tool exposed to or used by a Model Context Protocol server/client. MCP code should not be mixed directly into UI components.

For frontend projects:

src/
  app/ or pages/
  components/
  features/
    feature-name/
      components/
      hooks/
      services/
      schemas/
      types/
      utils/
      constants/
      index.ts
  lib/
  types/

For smaller projects:

src/
  components/
  hooks/
  services/
  utils/
  types/
  schemas/

Refactoring large files

For files over 800 lines, do not add more code casually. Propose a short refactor plan, preserve behavior, and extract one responsibility at a time.

A practical order:

1. Types, constants, and pure utilities.
2. Services and external calls.
3. Hooks and reusable behavior.
4. Presentational components.
5. A thin route, page, screen, or container that composes the pieces.

Run typecheck, lint, tests, or build when available.

MCP organization

MCP server, client, schema, and tool execution code should be isolated from UI. Prefer a dedicated MCP area:

src/
  mcp/
    servers/
    clients/
    tools/
    schemas/
    types/
    utils/

Feature-scoped MCP code is also fine:

src/
  features/
    assistant/
      mcp/
        tools/
        clients/
        schemas/
        types/

Avoid placing MCP client setup, tool definitions, schema validation, tool execution, and UI rendering in one component file.

Philosophy

This skill is intentionally small. It asks agents to think about structure before writing code, but it does not try to replace local conventions, human judgment, tests, or code review.

The goal is better defaults: fewer giant files, clearer responsibilities, safer refactors, and less cleanup after agent-generated code.

Roadmap

• More real-world examples for common stacks.
• Optional audit checklist for large files.
• More MCP organization examples.
• Framework-specific notes for Next.js, Remix, Expo, Node, and monorepos.
• Optional lightweight scripts only if they remain non-invasive.

Contributing

Contributions should keep modular-code-guard lightweight and practical. Prefer clear docs and examples before adding complexity. See CONTRIBUTING.md.