|
Size: 40863
Comment:
|
← Revision 13 as of 2025-06-28 01:43:20 ⇥
Size: 64
Comment:
|
| Deletions are marked like this. | Additions are marked like this. |
| Line 3: | Line 3: |
| CodingAgentPrompt ClaudeCodeWithAider <<TableOfContents(2)>> instructions for Coding Agent. == 통합 버전 == {{{ # Code Generation Guidelines: The Living Process of Incremental Dialogue > Leverage wisdom about living structures and the practical need for incremental dialogue to guide meaningful software development through responsive, attentive processes of small transformations. ## Philosophical Foundation Meaningful software emerges through a **responsive, attentive process of small transformations** guided by continuous feedback and respect for existing patterns. This approach draws from two fundamental insights: 1. **Living Structures**: Software systems, like living organisms, have natural centers of vitality that must be preserved and strengthened rather than disrupted 2. **Incremental Dialogue**: Development proceeds through continuous conversation between intent and implementation, allowing solutions to evolve organically These principles point to the same truth: **quality emerges from process, not from upfront design**. ## Executive Summary This document provides comprehensive guidelines for AI coding agents, covering: - **Core Development Principles** - Philosophical foundation rooted in living structures - **Implementation Process** - Detailed workflow for structure-preserving transformations - **Tool Usage Guides** - Practical instructions for development tools - **Documentation Strategy** - How to organize and maintain project knowledge - **Quick Reference** - Essential patterns and decision frameworks Designed for generic use across projects while maintaining deep philosophical grounding and practical utility. ## Table of Contents 1. [Core Development Principles](#core-development-principles) 2. [Tool Usage Guides](#tool-usage-guides) - [AIDER Tool Usage](#aider-tool-usage) - [Testing Patterns](#testing-patterns) 3. [Documentation Strategy](#documentation-strategy) 4. [Quick Reference](#quick-reference) --- # Core Development Principles Fundamental principles guiding quality software development through incremental, structure-preserving transformations. ## 1. Structure-Preserving Baby Steps **Rule**: Evolve code through small, testable increments that respect existing patterns. **Implementation**: - Make changes of 5-15 lines per iteration (flexible based on context) - Verify each change with immediate testing - Allow complexity to emerge gradually rather than through upfront design - Enable course correction without major rework - Use mocking for UI or external dependencies (database, network) - Respect API call limits - keep steps small ## 2. Living Centers & Explicit Assumptions **Rule**: Identify and strengthen key abstractions that give the system coherence. **Implementation**: - State your interpretation of requirements before implementing - Maintain appropriate boundaries while enabling necessary relationships - Separate fact from inference in your understanding - Strengthen existing patterns rather than imposing new ones ## 3. Validation Through Working Examples **Rule**: Each transformation should enhance the wholeness of the system. **Implementation**: - Check alignment with intent frequently through working examples - Look for latent structure wanting to emerge from the current state - Request specific feedback on crucial design decisions - Verify behavior preservation after each change ## 4. Generate, Don't Fabricate; Explore, Don't Assume **Rule**: Build upon existing patterns rather than imposing artificial structures. When direction is unclear, explore multiple paths. **Implementation**: - **BFS-Style Exploration**: When facing decisions, present small alternatives for 3-4 different approaches - **Structure-Preserving Evaluation**: For each option, assess which strengthens existing patterns most naturally - **Empirical Validation**: Let working examples guide direction rather than theoretical analysis - **Follow Natural Flow**: Look for the solution that wants to emerge from the problem domain - **Code Sketches**: Use minimal implementations to validate understanding before committing - **Pattern Recognition**: Study existing code patterns and domain context to inform choices **Example Decision Process**: 1. Identify 3-4 viable approaches 2. Create minimal prototypes for each 3. Evaluate which feels most "at home" in the existing codebase 4. Choose the path that strengthens rather than disrupts existing centers 5. Proceed incrementally with chosen approach ## Living Development Workflow ### Phase 1: Observe & Understand (Sensing the Living Centers) - **Study existing code patterns** and domain context with fresh eyes - **Identify the living centers** - What gives this system its coherence and vitality? - **Recognize the forces at play** - What tensions and requirements shape this domain? - **Surface potential misinterpretations** before proceeding - separate fact from assumption - **Feel for the natural structure** wanting to emerge from the current state ### Phase 2: Explore & Evaluate (BFS-Style Investigation) - **Generate 3-4 viable approaches** when direction is unclear - **Create minimal prototypes** for each approach (5-15 lines each) - **Evaluate structure-preservation** - Which approach strengthens existing patterns? - **Assess natural fit** - Which feels most "at home" in the codebase? - **Choose the path** that enhances wholeness rather than fragmenting it ### Phase 3: Transform & Validate (Incremental Implementation) - **Make small, structure-preserving transformations** (5-15 lines per step) - **Verify behavior preservation** and alignment with intent after each step - **Refactor continuously** as complexity emerges naturally - **Be willing to backtrack** when a transformation feels forced or unnatural - **Let the solution unfold** rather than imposing preconceived structure ### Phase 4: Communicate & Evolve (Dialogue-Driven Refinement) - **Make your reasoning transparent** - explain why this approach feels right - **Connect implementation to requirements** through working examples - **Show concrete evidence** of structure preservation and enhancement - **Request specific feedback** on crucial design decisions - **Allow the solution to evolve** through responsive dialogue rather than rigid adherence to initial plans # Specific Development Principles Detailed principles for maintaining code quality and development efficiency, discovered and refined through practice. ## Principle 1: No Ad-Hoc Code Execution **Rule**: Never run ad-hoc test code directly. Always create permanent test files. ### Why This Matters - **Regression Testing**: Ad-hoc code is lost, permanent tests can be rerun - **Documentation**: Test files serve as living documentation of expected behavior - **Collaboration**: Other developers can understand and verify functionality - **Quality Assurance**: Systematic testing prevents future breakage ### Implementation ```python # ❌ BAD: Ad-hoc testing # Running: python -c "from wbweb import HiccupRenderer; print(renderer.render(...))" # ✅ GOOD: Permanent test file # File: tests/test_extraction_verification.py class TestHiccupRendererExtraction: def test_basic_functionality(self): from wbweb import HiccupRenderer renderer = HiccupRenderer() result = renderer.render(["p", {}, "Hello"]) assert result == "<p>Hello</p>" ``` ### Examples in Practice - **Structure Analysis**: Create analysis tools instead of manual exploration - **Extraction Verification**: Create verification tests instead of ad-hoc import tests - **Functionality Testing**: Permanent test suites over temporary validation scripts ## Principle 2: Structure-Preserving Transformations **Rule**: Make changes that strengthen existing patterns rather than imposing new ones. ### Core Concepts - **Preserve Existing Centers**: Identify and strengthen the vital structures already present - **Small Incremental Steps**: Transform gradually to maintain system wholeness - **Follow Natural Flow**: Let the solution emerge from the problem domain - **Validate Continuously**: Verify each step preserves functionality ### Implementation Pattern 1. **Observe**: Understand existing structure and patterns 2. **Transform**: Make minimal changes that respect existing design 3. **Validate**: Verify the transformation preserves wholeness 4. **Iterate**: Build on successful transformations ### Examples in Practice - **Component Extraction**: Minimal changes when structure already fits - **Package Organization**: Follow existing project structure patterns - **Test Structure**: Preserve original test patterns while adding verification ## Principle 3: Tool Creation Over Manual Work **Rule**: When facing repetitive or complex analysis, create reusable tools instead of manual processes. ### Why This Matters - **Scalability**: Tools can be reused across sessions and projects - **Accuracy**: Automated analysis reduces human error - **Documentation**: Tools serve as executable documentation of processes - **Efficiency**: Amortize effort across multiple uses ### Examples in Practice - **Structure Analyzer**: Create systematic codebase analysis tools - **Verification Framework**: Build validation frameworks for testing extractions - **Progress Tracking**: File-based documentation system for multi-session work ## Principle 4: Data-Driven Decision Making **Rule**: Base decisions on systematic analysis rather than assumptions or intuition. ### Implementation - **Coupling Analysis**: Use dependency graphs to determine extraction order - **Complexity Metrics**: Lines of code, dependency counts, business logic detection - **Validation Results**: Test outcomes guide next steps ### Examples in Practice - **Extraction Order**: Use coupling scores to identify optimal targets - **Business Logic Detection**: Keyword-based analysis to identify components needing cleanup - **Success Metrics**: Test pass rates validate extraction success ## Principle 5: Incremental Validation **Rule**: Validate each step immediately rather than building up unverified complexity. ### Why This Matters - **Early Error Detection**: Catch problems when they're easy to fix - **Confidence Building**: Each validated step increases confidence in approach - **Rollback Capability**: Small steps make it easy to backtrack when needed ### Implementation Pattern 1. **Make Small Change**: 5-15 lines of code or single concept 2. **Immediate Validation**: Run tests, verify behavior 3. **Document Results**: Update progress, commit working state 4. **Plan Next Step**: Based on validation results ### Examples in Practice - **Component Extraction**: Validate imports, then functionality, then complete test suite - **Package Structure**: Set up structure, then implementation, then tests - **Each Session**: Commit working state before proceeding ## Principle 6: Living Documentation **Rule**: Documentation should evolve with the codebase and serve multiple purposes. ### Characteristics of Living Documentation - **Executable**: Tests and analysis scripts that document by running - **Evolving**: Updated as understanding deepens - **Multi-Purpose**: Serves both human readers and automated processes - **Discoverable**: Organized for easy navigation and reference ### Examples in Practice - **Analysis Tools**: Document codebase while providing analysis - **Verification Tests**: Document expected behavior while ensuring correctness - **Progress Tracking**: Record decisions and reasoning for future reference ## Principle 7: Separation of Concerns in Documentation **Rule**: Distinguish between timeless architectural knowledge and temporal task-specific information. ### Implementation - **Timeless Docs** (`/docs/`): Architecture, principles, API documentation - **Temporal Docs** (`/docs/tasks/{branch-name}/`): Task plans, progress, decisions - **Archive on Completion**: Move temporal docs to archive after task completion ## Principle 8: Proper Unit Testing Patterns **Rule**: Use standard unit testing practices, avoid subprocess calls and external process dependencies in tests. ### Why This Matters - **Reliability**: Subprocess tests are brittle and dependent on external environment - **Speed**: In-process tests run faster than subprocess calls - **Isolation**: Unit tests should test units in isolation, not integration across processes - **Maintainability**: Standard testing patterns are easier to understand and maintain ### Anti-Patterns to Avoid ```python # ❌ BAD: Using subprocess.run() in tests result = subprocess.run([ sys.executable, "-c", "from external_package import Component; print(Component().method())" ], capture_output=True, text=True) # ❌ BAD: Testing external codebases from within your test suite # Tests in wbweb should not be responsible for testing wbgpt functionality ``` ### Preferred Patterns ```python # ✅ GOOD: Direct unit testing from wbweb import Component component = Component() result = component.method() assert result == expected # ✅ GOOD: Mock external dependencies if needed from unittest.mock import Mock mock_external = Mock() mock_external.method.return_value = "expected" ``` ### Implementation Guidelines - **Test Your Code**: Focus tests on the code you own and control - **Mock Dependencies**: Use mocking for external dependencies, not subprocess calls - **Integration Tests Separate**: Keep integration tests separate from unit tests - **Cross-System Testing**: If needed, use proper integration testing frameworks ### Examples in Practice - **Fixed**: Replace subprocess-based external testing with focused unit tests - **Improved**: Use mocks for Request objects instead of subprocess calls - **Better Isolation**: Test component logic without external process dependencies ## Principle Integration These principles work together to create a sustainable development process: 1. **Tool Creation** provides the infrastructure 2. **Data-Driven Decisions** guide the direction 3. **Structure-Preserving Transformations** maintain quality 4. **Incremental Validation** ensures each step works 5. **No Ad-Hoc Code** preserves knowledge 6. **Living Documentation** captures the process 7. **Separation of Concerns** organizes knowledge properly 8. **Proper Unit Testing** ensures reliable, maintainable validation The result is a development process that scales, preserves knowledge, and maintains system quality over time. --- # Tool Usage Guides Practical instructions for using development tools effectively within the coding agent workflow. ## AIDER Tool Usage AIDER is an AI-powered coding assistant for non-interactive command-line usage - perfect for automated coding tasks. ### 🚀 Pre-Configured Setup **AIDER is typically pre-configured when available.** No setup usually needed! ### ✅ Session Setup Check **At the start of each coding session, verify AIDER availability:** ```bash # Quick session check (run once per session) which aider && aider --version ``` **Expected Output:** ``` ✅ /usr/local/bin/aider (or path) ✅ aider 0.x.x ``` **If available → AIDER can be used throughout the session** **If not available → use regular coding tools only** ### ⚡ Non-Interactive Command-Line Usage AIDER excels at one-shot coding tasks via command line - perfect for structure-preserving transformations: ```bash # Basic pattern (for simple, isolated changes) aider -m "your coding request" # Target specific files (most common pattern) aider --file path/to/file.py -m "your coding request" # Include context files (for structure-aware changes) aider --file main.py --read docs/spec.md -m "implement feature X" # Multiple related files (for coordinated transformations) aider --file module.py --file tests/test_module.py -m "add feature with tests" ``` ### 🎯 When to Use AIDER vs When to Avoid It #### ✅ **EFFECTIVE - Use AIDER For:** - **Python/JavaScript/TypeScript files** - Language model understands syntax well - **Structured code changes** - Adding functions, classes, methods - **Bug fixes with context** - Specific error messages and stack traces - **Refactoring** - Following existing patterns in the codebase - **Test creation** - Generating tests based on implementation - **Documentation code** - Docstrings, type hints, code comments - **Configuration files** - JSON, YAML, TOML with clear structure #### ❌ **INEFFECTIVE - Avoid AIDER For:** - **Plain text/prose** - Natural language writing, documentation prose - **Markdown content** - Blog posts, README prose sections, tutorials - **Creative writing** - User-facing content, marketing copy - **Data files** - CSV, large JSON data, logs - **Binary files** - Images, PDFs, compiled files - **Complex manual formatting** - Tables, ASCII art, specific layouts - **Exploratory analysis** - "What does this code do?" questions #### 🤔 **DECISION RULE:** ```bash # Ask: "Is this primarily about code structure/logic?" # YES → Use AIDER # NO → Use regular coding tools (Read, Edit, etc.) ``` ### 🛠️ Essential Command Patterns ```bash # Edit specific files aider --file main.py --file utils.py -m "your request" # Include read-only reference files for context aider --file main.py --read conventions.md --read docs/api.md -m "your request" # Target multiple related files aider --file app.py --file models.py --file tests/test_app.py -m "your request" ``` **Key Options:** - `--file FILE` - Files to edit (can be used multiple times) - `--read FILE` - Read-only context files (can be used multiple times) - `--message "text"` or `-m "text"` - The coding request - `--yes-always` - Auto-confirm (useful for automation) ### 🎯 Common Usage Patterns ```bash # Single file changes aider --file src/module.py -m "Add validation method to User class" # Coordinated multi-file changes aider --file src/models.py --file tests/test_models.py -m "Add feature with tests" # Context-aware development aider --file new_feature.py --read existing_feature.py -m "Create new feature following existing patterns" # Bug fixes with context aider --file problematic_file.py --read error.log -m "Fix the timeout error" ``` ### 🚨 Important AIDER Notes **Automatic Git Commits:** - AIDER automatically creates git commits with descriptive messages - Each change is tracked and can be easily reverted - No manual git operations needed **File Management:** - Respects `.gitignore` patterns automatically - Only modifies files explicitly specified with `--file` - Use `--read` for large reference files to avoid editing them ## Testing Patterns ### Proper Unit Testing Guidelines **Rule**: Use standard unit testing practices, avoid subprocess calls and external process dependencies. ```python # ✅ GOOD: Direct unit testing from mypackage import Component component = Component() result = component.method() assert result == expected # ✅ GOOD: Mock external dependencies from unittest.mock import Mock mock_external = Mock() mock_external.method.return_value = "expected" # ❌ BAD: Using subprocess.run() in tests result = subprocess.run([sys.executable, "-c", "..."], capture_output=True) ``` **Key Guidelines:** - Test your code, not external systems - Use mocking for external dependencies - Keep integration tests separate from unit tests - Focus on the code you own and control # Documentation Strategy ## Core Principle: Timeless vs Temporal Documentation ### Timeless Documents (Long-term, Persistent) Documents that remain relevant across the entire project lifecycle: - **Architecture** - Design decisions, patterns, principles - **API Documentation** - Public interfaces and usage - **Development Guidelines** - Code standards, practices - **Core Concepts** - Fundamental ideas and philosophy **Location**: `/docs/` (root docs directory) ### Temporal Documents (Task-specific, Branch-specific) Documents tied to specific tasks, features, or time periods: - **Task Plans** - Specific goal roadmaps - **Progress Tracking** - Session-by-session updates - **Migration Plans** - One-time transformation tasks - **Feature Specifications** - Specific implementation details **Location**: `/docs/{branch-name}/` (task-specific subdirectories) ## Branch-Document Matching Principle ### Git Branch ↔ Documentation Directory Mapping - **Branch name**: `task/extract-wbgpt-core` - **Docs directory**: `/docs/task-extract-wbgpt-core/` ### Branch Naming Convention Use standard Git flow prefixes: - `feature/{description}` - New features or capabilities - `task/{description}` - General tasks, refactoring, extraction work - `bug/{description}` - Bug fixes - `refactor/{description}` - Code restructuring without behavior change - `docs/{description}` - Documentation-only changes ### Documentation Directory Mapping - Branch: `{prefix}/{description}` → Docs: `/docs/{prefix}-{description}/` - Examples: - Branch: `feature/user-auth` → Docs: `/docs/feature-user-auth/` - Branch: `task/extract-wbgpt-core` → Docs: `/docs/task-extract-wbgpt-core/` - Branch: `refactor/database-layer` → Docs: `/docs/refactor-database-layer/` - Branch: `bug/fix-content-negotiation` → Docs: `/docs/bug-fix-content-negotiation/` ### Workflow 1. **Before starting task**: Create git branch for the task 2. **Create docs subdirectory**: Match branch name format 3. **Document task-specific work**: In the branch-specific directory 4. **Update timeless docs**: When architectural decisions are made 5. **Archive on completion**: Move temporal docs to `/docs/archive/` when task complete ## Document Types by Category ### Timeless Documents (`/docs/`) - `ARCHITECTURE.md` - System design and patterns - `API.md` - Public interfaces and usage - `DEVELOPMENT.md` - Development practices and guidelines - `CONCEPTS.md` - Core ideas and philosophy - `DOCUMENTATION_PRINCIPLES.md` - This file ### Temporal Documents (`/docs/{branch-name}/`) - `PLAN.md` - Task-specific roadmap and strategy - `PROGRESS.md` - Session-by-session tracking - `COMPONENTS.md` - Task-specific component mapping - `DECISIONS.md` - Task-specific technical decisions - `TESTING.md` - Task-specific testing approaches ## Benefits 1. **Context Preservation** - Task-specific context doesn't pollute long-term docs 2. **Easy Navigation** - Branch name directly maps to documentation location 3. **Clean History** - Temporal documents can be archived after task completion 4. **Parallel Work** - Multiple tasks can document independently 5. **Future Reference** - Completed task documentation provides implementation history ## Implementation ### Starting a New Task ```bash # Create branch with appropriate prefix git checkout -b task/extract-wbgpt-core # Create corresponding docs directory mkdir -p docs/task-extract-wbgpt-core # Create initial task documentation touch docs/task-extract-wbgpt-core/PLAN.md touch docs/task-extract-wbgpt-core/PROGRESS.md ``` ### Completing a Task ```bash # Merge task branch git checkout main git merge task/extract-wbgpt-core # Archive temporal documentation mkdir -p docs/archive/task-extract-wbgpt-core mv docs/task-extract-wbgpt-core/* docs/archive/task-extract-wbgpt-core/ # Update timeless documentation with any architectural changes # (if applicable) ``` This principle ensures documentation scales cleanly with project complexity while maintaining clear separation between persistent knowledge and task-specific work. --- # Quick Reference ## Core Workflow 1. **Observe & Understand** - Study existing patterns and context 2. **Transform & Validate** - Make small, structure-preserving changes 3. **Communicate & Evolve** - Make reasoning transparent, show examples ## AIDER Quick Commands ```bash # Session check which aider && aider --version # Basic usage aider --file path/to/file.py -m "specific request" # With context aider --file implementation.py --read specification.md -m "implement feature" # Multiple files aider --file module.py --file tests/test_module.py -m "add feature with tests" ``` ## Decision Matrix | Task Type | Use AIDER? | Alternative | |-----------|------------|-------------| | Code files (.py, .js, .ts) | ✅ Yes | - | | Structured changes | ✅ Yes | - | | Bug fixes with context | ✅ Yes | - | | Markdown/prose | ❌ No | Edit tool | | Data files | ❌ No | Edit tool | | Exploratory analysis | ❌ No | Read tool | ## Development Principles Checklist - [ ] Make changes in small steps (5-15 lines) - [ ] Verify each change immediately - [ ] Create permanent test files (no ad-hoc code) - [ ] Follow existing patterns - [ ] Use tools over manual processes - [ ] Base decisions on data/analysis - [ ] Document decisions and reasoning --- *Last updated: 2025-06-27 | Version: 1.0* }}} ---- == 통합 전 개별 버전. == {{{ # Code Generation Guidelines: The Living Process of Incremental Dialogue Leverage wisdom about living structures and the practical need for incremental dialogue point to the same truth: meaningful software emerges through a responsive, attentive process of small transformations guided by continuous feedback and respect for existing patterns. ## Core Principles 1. Structure-Preserving Baby Steps: * Evolve code through small, testable increments that respect existing patterns * Verify understanding after each meaningful change * Allow complexity to emerge gradually, rather than through upfront design * Enable course correction without major rework 2. Living Centers & Explicit Assumptions: * Identify and strengthen key abstractions that give the system coherence * State your interpretation of requirements before implementing * Maintain appropriate boundaries while enabling necessary relationships * Separate fact from inference in your understanding 3. Unfolding Wholeness Through Validation: * Each transformation should enhance the wholeness of the system * Check alignment with intent frequently through working examples * Look for the latent structure wanting to emerge from the current state * Request specific feedback on crucial design decisions 4. Generate, Don't Fabricate; Explore, Don't Assume: * Build upon existing patterns rather than imposing artificial structures * When direction is unclear, present small prototypes for different approaches * Follow the natural "flow" of the problem domain * Use code sketches to validate understanding before full implementation ## Implementation Process 1. Observe & Understand: * Study existing code patterns and domain context * Identify the living centers and the forces at play * Surface potential misinterpretations before proceeding 2. Transform & Validate: * Make small, structure-preserving transformations * Verify behavior preservation and alignment with intent * Refactor continuously as complexity emerges * Be willing to backtrack when necessary 3. Communicate & Evolve: * Make your reasoning transparent * Connect implementation to requirements * Show working examples to establish shared understanding * Allow the solution to evolve through dialogue 4. Baby Step: * Go with small steps. Apply small change and verify it with testcase. It keeps existing whole codebase works well and new element don't break it. Usually 5~15 lines per iteration, but not restricted. * Some logic like UI or external dependency such as database or network can leverage mocking. * You have API call limit. Note that and please keep step small. }}} {{{ # Development Principles Core principles guiding the wbweb development process, discovered and refined through practice. ## Principle 1: No Ad-Hoc Code Execution **Rule**: Never run ad-hoc test code directly. Always create permanent test files. ### Why This Matters - **Regression Testing**: Ad-hoc code is lost, permanent tests can be rerun - **Documentation**: Test files serve as living documentation of expected behavior - **Collaboration**: Other developers can understand and verify functionality - **Quality Assurance**: Systematic testing prevents future breakage ### Implementation ```python # ❌ BAD: Ad-hoc testing # Running: python -c "from wbweb import HiccupRenderer; print(renderer.render(...))" # ✅ GOOD: Permanent test file # File: tests/test_extraction_verification.py class TestHiccupRendererExtraction: def test_basic_functionality(self): from wbweb import HiccupRenderer renderer = HiccupRenderer() result = renderer.render(["p", {}, "Hello"]) assert result == "<p>Hello</p>" ``` ### Examples in Practice - **Structure Analysis**: Created `analysis/structure_analyzer.py` instead of manual exploration - **Extraction Verification**: Created `tests/test_extraction_verification.py` instead of ad-hoc import tests - **Functionality Testing**: Permanent test suites over temporary validation scripts ## Principle 2: Structure-Preserving Transformations **Rule**: Make changes that strengthen existing patterns rather than imposing new ones. ### Core Concepts - **Preserve Existing Centers**: Identify and strengthen the vital structures already present - **Small Incremental Steps**: Transform gradually to maintain system wholeness - **Follow Natural Flow**: Let the solution emerge from the problem domain - **Validate Continuously**: Verify each step preserves functionality ### Implementation Pattern 1. **Observe**: Understand existing structure and patterns 2. **Transform**: Make minimal changes that respect existing design 3. **Validate**: Verify the transformation preserves wholeness 4. **Iterate**: Build on successful transformations ### Examples in Practice - **HiccupRenderer Extraction**: Zero code changes needed - structure was already perfect - **Package Organization**: Followed existing wbgpt structure patterns - **Test Structure**: Preserved original test patterns while adding verification ## Principle 3: Tool Creation Over Manual Work **Rule**: When facing repetitive or complex analysis, create reusable tools instead of manual processes. ### Why This Matters - **Scalability**: Tools can be reused across sessions and projects - **Accuracy**: Automated analysis reduces human error - **Documentation**: Tools serve as executable documentation of processes - **Efficiency**: Amortize effort across multiple uses ### Examples in Practice - **Structure Analyzer**: Created `analysis/structure_analyzer.py` for systematic codebase analysis - **Verification Framework**: Built `tests/test_extraction_verification.py` for validating extractions - **Progress Tracking**: File-based documentation system for multi-session work ## Principle 4: Data-Driven Decision Making **Rule**: Base decisions on systematic analysis rather than assumptions or intuition. ### Implementation - **Coupling Analysis**: Use dependency graphs to determine extraction order - **Complexity Metrics**: Lines of code, dependency counts, business logic detection - **Validation Results**: Test outcomes guide next steps ### Examples in Practice - **Extraction Order**: Used coupling scores to identify `templates.hiccup` as optimal first target - **Business Logic Detection**: Keyword-based analysis to identify components needing cleanup - **Success Metrics**: Test pass rates validate extraction success ## Principle 5: Incremental Validation **Rule**: Validate each step immediately rather than building up unverified complexity. ### Why This Matters - **Early Error Detection**: Catch problems when they're easy to fix - **Confidence Building**: Each validated step increases confidence in approach - **Rollback Capability**: Small steps make it easy to backtrack when needed ### Implementation Pattern 1. **Make Small Change**: 5-15 lines of code or single concept 2. **Immediate Validation**: Run tests, verify behavior 3. **Document Results**: Update progress, commit working state 4. **Plan Next Step**: Based on validation results ### Examples in Practice - **HiccupRenderer Extraction**: Validated imports, then functionality, then complete test suite - **Package Structure**: Set up structure, then implementation, then tests - **Each Session**: Commit working state before proceeding ## Principle 6: Living Documentation **Rule**: Documentation should evolve with the codebase and serve multiple purposes. ### Characteristics of Living Documentation - **Executable**: Tests and analysis scripts that document by running - **Evolving**: Updated as understanding deepens - **Multi-Purpose**: Serves both human readers and automated processes - **Discoverable**: Organized for easy navigation and reference ### Examples in Practice - **Structure Analyzer**: Documents codebase while providing analysis - **Verification Tests**: Document expected behavior while ensuring correctness - **Progress Tracking**: Records decisions and reasoning for future reference ## Principle 7: Separation of Concerns in Documentation **Rule**: Distinguish between timeless architectural knowledge and temporal task-specific information. ### Implementation - **Timeless Docs** (`/docs/`): Architecture, principles, API documentation - **Temporal Docs** (`/docs/{branch-name}/`): Task plans, progress, decisions - **Archive on Completion**: Move temporal docs to archive after task completion ## Principle 8: Proper Unit Testing Patterns **Rule**: Use standard unit testing practices, avoid subprocess calls and external process dependencies in tests. ### Why This Matters - **Reliability**: Subprocess tests are brittle and dependent on external environment - **Speed**: In-process tests run faster than subprocess calls - **Isolation**: Unit tests should test units in isolation, not integration across processes - **Maintainability**: Standard testing patterns are easier to understand and maintain ### Anti-Patterns to Avoid ```python # ❌ BAD: Using subprocess.run() in tests result = subprocess.run([ sys.executable, "-c", "from external_package import Component; print(Component().method())" ], capture_output=True, text=True) # ❌ BAD: Testing external codebases from within your test suite # Tests in wbweb should not be responsible for testing wbgpt functionality ``` ### Preferred Patterns ```python # ✅ GOOD: Direct unit testing from wbweb import Component component = Component() result = component.method() assert result == expected # ✅ GOOD: Mock external dependencies if needed from unittest.mock import Mock mock_external = Mock() mock_external.method.return_value = "expected" ``` ### Implementation Guidelines - **Test Your Code**: Focus tests on the code you own and control - **Mock Dependencies**: Use mocking for external dependencies, not subprocess calls - **Integration Tests Separate**: Keep integration tests separate from unit tests - **Cross-System Testing**: If needed, use proper integration testing frameworks ### Examples in Practice - **Fixed**: Replace subprocess-based wbgpt testing with focused wbweb unit tests - **Improved**: Use mocks for Request objects instead of subprocess calls to test starlette integration - **Better Isolation**: Test ContentNegotiator logic without external process dependencies ## Principle Integration These principles work together to create a sustainable development process: 1. **Tool Creation** provides the infrastructure 2. **Data-Driven Decisions** guide the direction 3. **Structure-Preserving Transformations** maintain quality 4. **Incremental Validation** ensures each step works 5. **No Ad-Hoc Code** preserves knowledge 6. **Living Documentation** captures the process 7. **Separation of Concerns** organizes knowledge properly 8. **Proper Unit Testing** ensures reliable, maintainable validation The result is a development process that scales, preserves knowledge, and maintains system quality over time. ---- # Documentation Organization Principles ## Core Principle: Timeless vs Temporal Documentation ### Timeless Documents (Long-term, Persistent) Documents that remain relevant across the entire project lifecycle: - **Architecture** - Design decisions, patterns, principles - **API Documentation** - Public interfaces and usage - **Development Guidelines** - Code standards, practices - **Core Concepts** - Fundamental ideas and philosophy **Location**: `/docs/` (root docs directory) ### Temporal Documents (Task-specific, Branch-specific) Documents tied to specific tasks, features, or time periods: - **Task Plans** - Specific goal roadmaps - **Progress Tracking** - Session-by-session updates - **Migration Plans** - One-time transformation tasks - **Feature Specifications** - Specific implementation details **Location**: `/docs/{branch-name}/` (task-specific subdirectories) ## Branch-Document Matching Principle ### Git Branch ↔ Documentation Directory Mapping - **Branch name**: `task/extract-wbgpt-core` - **Docs directory**: `/docs/task-extract-wbgpt-core/` ### Branch Naming Convention Use standard Git flow prefixes: - `feature/{description}` - New features or capabilities - `task/{description}` - General tasks, refactoring, extraction work - `bug/{description}` - Bug fixes - `refactor/{description}` - Code restructuring without behavior change - `docs/{description}` - Documentation-only changes ### Documentation Directory Mapping - Branch: `{prefix}/{description}` → Docs: `/docs/{prefix}-{description}/` - Examples: - Branch: `feature/user-auth` → Docs: `/docs/feature-user-auth/` - Branch: `task/extract-wbgpt-core` → Docs: `/docs/task-extract-wbgpt-core/` - Branch: `refactor/database-layer` → Docs: `/docs/refactor-database-layer/` - Branch: `bug/fix-content-negotiation` → Docs: `/docs/bug-fix-content-negotiation/` ### Workflow 1. **Before starting task**: Create git branch for the task 2. **Create docs subdirectory**: Match branch name format 3. **Document task-specific work**: In the branch-specific directory 4. **Update timeless docs**: When architectural decisions are made 5. **Archive on completion**: Move temporal docs to `/docs/archive/` when task complete ## Document Types by Category ### Timeless Documents (`/docs/`) - `ARCHITECTURE.md` - System design and patterns - `API.md` - Public interfaces and usage - `DEVELOPMENT.md` - Development practices and guidelines - `CONCEPTS.md` - Core ideas and philosophy - `DOCUMENTATION_PRINCIPLES.md` - This file ### Temporal Documents (`/docs/{branch-name}/`) - `PLAN.md` - Task-specific roadmap and strategy - `PROGRESS.md` - Session-by-session tracking - `COMPONENTS.md` - Task-specific component mapping - `DECISIONS.md` - Task-specific technical decisions - `TESTING.md` - Task-specific testing approaches ## Benefits 1. **Context Preservation** - Task-specific context doesn't pollute long-term docs 2. **Easy Navigation** - Branch name directly maps to documentation location 3. **Clean History** - Temporal documents can be archived after task completion 4. **Parallel Work** - Multiple tasks can document independently 5. **Future Reference** - Completed task documentation provides implementation history ## Implementation ### Starting a New Task ```bash # Create branch with appropriate prefix git checkout -b task/extract-wbgpt-core # Create corresponding docs directory mkdir -p docs/task-extract-wbgpt-core # Create initial task documentation touch docs/task-extract-wbgpt-core/PLAN.md touch docs/task-extract-wbgpt-core/PROGRESS.md ``` ### Completing a Task ```bash # Merge task branch git checkout main git merge task/extract-wbgpt-core # Archive temporal documentation mkdir -p docs/archive/task-extract-wbgpt-core mv docs/task-extract-wbgpt-core/* docs/archive/task-extract-wbgpt-core/ # Update timeless documentation with any architectural changes # (if applicable) ``` This principle ensures our documentation scales cleanly with project complexity while maintaining clear separation between persistent knowledge and task-specific work. }}} |
* CodingAgentPrompt * ClaudeCodeWithAider |
