Claude-skill-registry architecting-structure

Enforces "Feature-First" architecture across standard frameworks. Use to scaffold new projects, refactor messy ones, or enforce clean file organization rules.

install

source · Clone the upstream repo

git clone https://github.com/majiayu000/claude-skill-registry

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/majiayu000/claude-skill-registry "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/data/architecting-structure" ~/.claude/skills/majiayu000-claude-skill-registry-architecting-structure && rm -rf "$T"

manifest: skills/data/architecting-structure/SKILL.md

source content

Code Structure Architect

When to use this skill

When the user asks to "set up the folders" for a new project.
When the user asks to "clean up" or "refactor" a messy directory.
When the user asks "where should I put this file?".
When starting any new Next.js, Flutter, Python, or standard web project.

Core Philosophy: Feature-First

We strictly follow Feature-First Architecture (Vertical Slicing). Code that changes together stays together.

Bad (Type-First):
```
/components
```
,
```
/hooks
```
,
```
/services
```
(Separates logic by file type).
Good (Feature-First):
```
/features/auth
```
,
```
/features/dashboard
```
(Groups explicitly by user value).

Workflow

1. Scaffolding (New Project)

Identify Framework: Detect if it's Next.js, Flutter, Python, etc.
Apply Template: Use the specific directory map below.
Create Core: Generate
```
core/
```
(shared logic) and
```
features/
```
(business logic) folders immediately.

2. Refactoring (Cleanup)

Audit: List all files.
Group: Identify "features" (e.g., "Login", "Profile", "Feed").
Move:
- Move generic UI (buttons, cards) ->
```
components/ui/
```
  .
- Move shared utilities (dates, formatting) ->
```
utils/
```
  .
- Move feature logic ->
```
features/<feature-name>/
```
  .
Export: Create barrel files (
```
index.ts
```
/
```
barrier.dart
```
) only for the public API of a feature.

3. Enforcement (Check)

Review: Check if a new file is being created in the root or a 'dump' folder.
Block: "Stop. This belongs in
```
features/<name>
```
. Do not put logic in
```
pages/
```
."

Framework Standards

A. Next.js (App Router)

```
app/
```
: Routing layer ONLY. (page.tsx, layout.tsx, route.ts). NO LOGIC.
- ```
app/(auth)/login/page.tsx
```
  -> Imports from
```
@/features/auth
```

features/

: The brain.

```
features/auth/components/LoginForm.tsx
```
```
features/auth/hooks/useLogin.ts
```
```
features/auth/actions/login.ts
```
(Server Actions)

components/

: Shared dumb UI.

```
components/ui/button.tsx
```
(Shadcn)
```
components/layout/header.tsx
```

```
lib/
```
: Singletons (Prisma, Stripe, Redis clients).

B. Flutter (Clean + Riverpod)

```
lib/main.dart
```
: Entry point.
```
lib/core/
```
: Routing, Themes, Constants, Extensions.

lib/features/

```
features/auth/presentation/screens/
```
```
features/auth/presentation/widgets/
```
```
features/auth/data/repositories/
```
```
features/auth/domain/models/
```

```
lib/shared/
```
: Widgets used across multiple features.

C. Python (FastAPI / General)

```
app/main.py
```
: App init.
```
app/core/
```
: Config, Security, DB session.
```
app/routers/
```
: V1 endpoints.
```
app/internal/
```
: Admin routes.
```
app/services/
```
(Optional): If logic is heavy.
Note: Python often prefers flat structures initially. Group by "Domain" (e.g.,
```
app/users/
```
,
```
app/items/
```
) if the app grows.

Best Practices (Recommended)

Filenames:
- JS/TS:
```
camelCase
```
  for variables/functions,
```
PascalCase
```
  for Components/Classes,
```
kebab-case
```
  for folders/routes.
- Dart: always
```
snake_case
```
  for filenames.
- Python: always
```
snake_case
```
  .
Barrel Files: Avoid them for internal usage (causes circular deps). Use them ONLY to expose a Feature's public API to the rest of the app:
- Right:
```
import { LoginForm } from '@/features/auth'
```
  (where
```
features/auth/index.ts
```
  exists).
- Wrong:
```
import { Button } from '@/components'
```
  (import directly:
```
@/components/Button
```
  ).

Self-Correction Checklist

Before creating a file, ask:

"Is this file specific to one feature (e.g., 'Delete Task Button')?" -> Put in
```
features/tasks/components
```
.
"Is this file generic (e.g., 'Red Delete Button')?" -> Put in
```
components/ui
```
.
"Is this file a page?" -> Put in
```
app/
```
(Next.js) or
```
screens/
```
(Flutter), but keep it empty (logic goes to feature).