Development Rules: YAGNI, KISS, DRY

Every agent operating inside GigiKit follows a non-negotiable set of development rules. These rules exist to keep the codebase manageable for both humans and LLMs.

Core Principles

Three principles govern every implementation decision:

• YAGNI — You Aren’t Gonna Need It. Do not add code for hypothetical future requirements.
• KISS — Keep It Simple, Stupid. Prefer the simplest solution that correctly solves the problem.
• DRY — Don’t Repeat Yourself. Extract shared logic into modules; never copy-paste logic across files.

File Naming

Use kebab-case for all file names, and make names descriptive enough that an LLM reading a directory listing understands the file’s purpose without opening it.

# Good file names
user-authentication-service.ts
parse-markdown-frontmatter.ts
github-webhook-event-handler.ts

# Bad file names
utils.ts
helper.js
service2.ts

Long names are fine. A name like stripe-webhook-payment-intent-handler.ts is better than stripeHandler.ts.

File Size: 200-Line Limit

Keep individual code files under 200 lines. When a file approaches that limit, split it before adding more code.

Strategies for splitting:

• Extract utility functions into a dedicated *-utils.ts module
• Move business logic into a dedicated service class file
• Separate data-access concerns from presentation or API concerns
• Use composition over inheritance for complex components

Code Quality Guidelines

• Prioritize functionality and readability over strict style enforcement
• Ensure there are no syntax errors and all code compiles — run the compile command after every file change
• Use try/catch error handling and apply appropriate security measures
• Write self-documenting code; add comments only for logic that cannot explain itself through naming
• After every implementation, delegate to code-reviewer to audit the result

Pre-Commit Rules

Before committing:

1. Run the linter — fix all errors (warnings are acceptable)
2. Run tests — do not ignore failing tests to unblock the build
3. Review staged files — never commit .env, API keys, or database credentials
4. Write a conventional commit message: feat:, fix:, docs:, refactor:, test:, chore:
5. Keep commits focused — one logical change per commit

# Pre-commit sequence
# Lint
npm run lint

# Test
npm test

# Commit with conventional message
git commit -m "feat: add stripe webhook payment intent handler"

Do Not Create Parallel Files

Never create a “new enhanced version” of an existing file. Always edit the original.

# Wrong pattern - Do NOT do this
src/auth/user-service.ts          ← original
src/auth/user-service-enhanced.ts ← new "improved" version

# Correct pattern - Always edit the original
src/auth/user-service.ts          ← updated in place

Skills to Activate

Related Guides

• Team Coordination Rules — rules specific to multi-agent team sessions
• The 6-Step Development Workflow — where these rules apply in the pipeline