feat: add AI coding agent guidelines and enhance coding standards (#14)

Implements comprehensive guidelines for AI coding assistants to ensure
consistent code quality and adherence to project standards.

Changes:
- Add AICodingAgent.md with mandatory workflow for AI assistants
- Enhance CODING_STANDARDS.md with "Simplicity First" principle
- Add "Code Smells and Anti-Patterns to Avoid" section
- Reference existing documentation rather than duplicating content

The guidelines emphasize reading all dev-notes documentation, running
quality checks before commits, and following established conventions.

Fixes #8

Author: florath

AICodingAgent.md

@@ -0,0 +1,83 @@
+# AI Coding Agent Guidelines
+
+**Project:** Aletheia-Probe - Journal Assessment Tool
+**Purpose:** Explicit instructions for AI coding assistants
+
+---
+
+## 1. Before Making ANY Changes (MANDATORY)
+
+Read and follow ALL standards in:
+
+- **`dev-notes/CODING_STANDARDS.md`** - All coding conventions, patterns, code smells to avoid
+- **`dev-notes/LOGGING_USAGE.md`** - Dual-logger system usage
+- **`dev-notes/DEPENDENCIES.md`** - Dependencies information
+- **`dev-notes/NORMALIZED_DATABASE_DESIGN.md`** - Database schema (if working with data)
+- **`dev-notes/integration/*.md`** - Data sources (if working with backends)
+
+Also:
+- Review recent commits to understand current patterns
+- Check open issues and PRs for ongoing work
+- Remember: This tool affects real academic decisions - quality is paramount
+
+---
+
+## 2. Pre-Commit Workflow (MANDATORY)
+
+Before ANY commit, run:
+
+```bash
+bash scripts/run-quality-checks.sh
+```
+
+**Requirements:**
+- ALL checks MUST pass
+- Do NOT commit failing code
+- Do NOT bypass checks
+- Do NOT use `type: ignore` without justification
+
+---
+
+## 3. Commit and PR Format
+
+### Commits
+
+Follow conventional commits (see `git log` for examples):
+
+```
+<type>: <subject ≤72 chars>
+
+<WHY, not just WHAT>
+```
+
+Types: `feat:`, `fix:`, `docs:`, `test:`, `refactor:`, `chore:`
+
+### Pull Requests
+
+Include:
+- **Summary**: What does this do?
+- **Motivation**: Why is this needed?
+- **Testing**: How was this tested?
+- **Checklist**: Quality checks pass, tests added, docs updated
+
+---
+
+## Summary Checklist
+
+✅ **DO:**
+1. Read all `dev-notes/` documentation first
+2. Run `bash scripts/run-quality-checks.sh` before committing
+3. Follow CODING_STANDARDS.md (simplicity, f-strings, type hints, enums, etc.)
+4. Follow LOGGING_USAGE.md (dual-logger system)
+5. Write tests for new functionality
+6. Add docstrings (Google style)
+7. Write clear commit messages explaining WHY
+
+❌ **DO NOT:**
+1. Commit code that fails quality checks
+2. Modify code you don't understand
+3. Introduce code smells (see CODING_STANDARDS.md)
+4. Add unnecessary dependencies
+5. Use backwards-compatibility hacks
+
+**When uncertain, ask for clarification.**

dev-notes/CODING_STANDARDS.md

@@ -23,6 +23,7 @@ This project adheres to the following Python Enhancement Proposals (PEPs) and co
 
 ## Table of Contents
 
+0. [Core Principle: Simplicity First](#core-principle-simplicity-first)
 1. [Python Version and Tools](#python-version-and-tools)
 2. [Project-Specific Conventions](#project-specific-conventions)
 3. [Domain-Specific Patterns](#domain-specific-patterns)
@@ -32,6 +33,30 @@ This project adheres to the following Python Enhancement Proposals (PEPs) and co
 
 ---
 
+## Core Principle: Simplicity First
+
+**MANDATORY**: Simple solutions are ALWAYS preferred over complex ones.
+
+- Choose the most straightforward implementation that solves the problem
+- Avoid over-engineering or premature optimization
+- Only add complexity when absolutely necessary and well-justified
+- Refactor complex code to be simpler when possible
+- If a simple solution works, use it
+
+**Example:**
+```python
+# GOOD - Simple and clear
+def is_empty(text: str) -> bool:
+    return not text.strip()
+
+# BAD - Unnecessarily complex (unless you need regex for specific validation)
+def is_empty(text: str) -> bool:
+    import re
+    return bool(re.match(r"^\s*$", text))
+```
+
+---
+
 ## Python Version and Tools
 
 ### Target Environment
@@ -354,16 +379,44 @@ class TestJournalAssessment:
 
 ---
 
+## Code Smells and Anti-Patterns to Avoid
+
+### Common Code Smells
+
+Do NOT introduce these code quality issues:
+
+- **Code Duplication** - Extract common code into reusable functions or classes
+- **Magic Numbers/Strings** - Use named constants or enums (see Project-Specific Conventions above)
+- **Long Functions** - Break down functions longer than 50 lines into smaller, focused functions
+- **Deep Nesting** - Use guard clauses and early returns to flatten conditionals
+- **Mutable Default Arguments** - Use `None` as default and initialize inside the function
+- **Bare Exceptions** - Catch specific exception types instead of generic `except:`
+- **God Objects** - Keep classes focused and cohesive with single responsibility
+
+### Development Practices to Avoid
+
+- **Skipping Quality Checks** - Always run quality checks before committing (see `scripts/run-quality-checks.sh`)
+- **Modifying Unknown Code** - Don't make changes in areas you don't fully understand
+- **Adding Unnecessary Dependencies** - Use standard library when possible; justify new dependencies
+- **Backwards-Compatibility Hacks** - Delete unused code cleanly; avoid underscore prefixes or commented-out code
+- **Using `type: ignore` Without Justification** - Fix type issues properly or provide clear reasoning
+
+**When uncertain about any change, ask for clarification before proceeding.**
+
+---
+
 ## Summary
 
 This coding standards document references established Python best practices (PEPs and community guidelines) and defines project-specific conventions for:
 
+- **Simplicity First**: Prefer simple solutions over complex ones
 - **String Formatting**: Exclusive use of f-strings
 - **Type Safety**: Comprehensive type hints with modern syntax
 - **Domain Patterns**: Custom exceptions, retry decorators, async patterns
 - **Security**: Input validation, SQL injection prevention, path traversal protection
 - **Database**: Parameterized queries and batch operations
 - **Testing**: Descriptive naming and fixture organization
 - **Quality**: Automated tooling (Black, isort, mypy, ruff, pytest)
+- **Code Quality**: Avoid code smells and anti-patterns
 
 All new code must follow these guidelines. When modifying existing code, bring it up to these standards where practical.