11 Core Principles

These are embedded in every template

The 11 principles are included in the AGENTS.md template. Download it to get them in your project.

Download AGENTS.md View full toolkit

Every project following Ydun AI Workflow enforces these 11 principles. They are non-negotiable, apply to every task, and persist after AI context compression. They’re embedded in the AGENTS.md template so every AI session starts with them.

1. KISS (Keep It Simple, Stupid)

• Avoid over-complication and over-engineering
• Choose simple solutions over complex ones
• Question every abstraction layer
• If a feature seems complex, ask: “Is there a simpler way?“

2. TDD (Test-Driven Development)

• Write tests first
• Run tests to ensure they fail (Red phase)
• Write minimal code to pass tests (Green phase)
• Refactor while keeping tests green
• Never commit code without tests

3. Separation of Concerns (SOC)

• Each module/component has a single, well-defined responsibility
• Clear boundaries between different parts of the system
• Services should be loosely coupled
• Avoid mixing business logic with UI or data access code

4. DRY (Don’t Repeat Yourself)

• Eliminate code duplication
• Extract common functionality into reusable components
• Use configuration files for repeated settings
• Create shared libraries for common operations

5. Documentation Standards

• Always include the actual date when writing documentation
• Use objective, factual language only
• Avoid marketing terms like “production-ready”, “world-class”, “cutting-edge”
• State current development status clearly
• Document what IS, not what WILL BE

5.5. AI-Optimized Documentation

Why 5.5? Because this extends Principle 5 — it applies the same documentation-first thinking specifically to AI consumption. It’s not a separate principle, it’s the other half of the same coin.

Documentation is structured data for both humans AND AI consumption. This principle adds 7 sub-principles:

1. Structured Data Over Prose — Use tables, JSON, YAML instead of paragraphs
2. Explicit Context — Never assume prior knowledge
3. Cause-Effect Relationships — Clear “if X then Y” statements
4. Machine-Readable Formats — Consistent, parseable metadata (dates, versions, status)
5. Searchable Content — Keywords, anchors, consistent terminology
6. Version-Stamped — Date all documentation updates
7. Cross-Referenced — Explicit links between related docs

When to apply:

• Projects with >5 documentation files: use full standards
• Multi-service platforms: essential for navigation
• Long-lived projects >3 months: worth the investment
• Simple scripts: lightweight approach is fine

See the full Documentation Standards reference.

6. Jimmy’s Workflow v2.1 (Red/Green Checkpoints)

Mandatory for all implementation tasks:

PRE-FLIGHT → IMPLEMENT → VALIDATE → CHECKPOINT

• PRE-FLIGHT: Verify context — do I have all files, requirements, dependencies?
• IMPLEMENT: Write code, build features, make changes
• VALIDATE: Run explicit validation with documented reasoning and confidence level
• CHECKPOINT: Mark completion with confidence level and validity conditions

Confidence levels:

• HIGH: Proceed automatically
• MEDIUM: Human spot-check recommended
• LOW: Human validation required

See the full Jimmy’s Workflow v2.1 reference.

7. YAGNI (You Ain’t Gonna Need It)

• Don’t implement features until they’re actually needed
• Resist the urge to “future-proof” or add “might be useful later” code
• Build for current requirements, not hypothetical future ones
• Question every feature: “Do we need this NOW?”
• Refactor when requirements change, don’t pre-optimize
• Every line of code is a liability — only write what’s necessary

AI assistant reminder: Don’t add “helpful” features like caching, abstraction layers, or config systems unless explicitly required by current needs.

8. Fix Now, Not Later

• Fix vulnerabilities immediately when discovered
• Fix warnings immediately (don’t suppress or accumulate)
• Fix failing tests immediately (understand root cause, don’t skip)
• Fix linter errors immediately (don’t disable rules without reason)
• Don’t use suppressions (@ts-ignore, eslint-disable, etc.) without documented justification

Exception clause: If you must defer an issue:

1. Investigate the root cause thoroughly
2. Weigh multiple solution options
3. Make an explicit decision
4. Document why
5. Create a tracking issue

9. Measure Twice, Cut Once

• Always verify your understanding before executing
• Double-check file paths, command syntax, and target locations
• Review the plan before implementation begins
• Confirm assumptions with explicit checks (read the file, run the test)
• When in doubt, investigate first — don’t guess

AI assistant reminder: Before making changes, explicitly verify: Is this the right file? Is this the right approach? Did I understand the requirement correctly?

10. No Shortcuts (Do It Right)

• Complete the job properly — no half-finished work
• Don’t skip steps to save time
• Implement the full solution, not a “good enough” hack
• If something needs 5 steps, do all 5 steps
• Quality over speed — cutting corners creates debt

AI assistant reminder: Never say “we can skip this for now” or “this should be good enough”. Complete the task fully.

11. Rules Persist (Context Compression Immunity)

• All rules remain in effect after auto-compact/context summarization
• Core principles are NEVER optional, regardless of context length
• If you can’t remember a rule, re-read AGENTS.md
• Summarization does not equal permission to skip validation
• Jimmy’s Workflow gates apply to EVERY task, not just “important” ones

Why this exists: Long AI sessions trigger context compression, which can cause the AI to “forget” constraints. This principle explicitly states that compression doesn’t remove obligations. All 11 principles apply with full force regardless of conversation length.