From 72251ee06a155d0f66ad1b2081675e2f81778653 Mon Sep 17 00:00:00 2001 From: Paul Duvall Date: Thu, 11 Dec 2025 15:20:43 -0500 Subject: [PATCH 1/2] docs: fix anti-pattern naming and add length guidelines MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Two improvements to pattern documentation: 1. Progressive Disclosure pattern - Fix anti-pattern naming - Changed "No Loading Guidance" to "Missing Guidance" - Now complies with pattern-spec naming rules (negative prefix required) - "Missing" is a proper negative adjective per spec guidelines 2. Pattern Specification - Add Pattern Length Guidelines - Complete pattern: 200-400 lines (target), 600 lines max - Description: 1-2 sentences - Core implementation: 150-300 lines - Individual anti-patterns: 50-100 lines each - Code examples in README: 30-50 lines max Enforcement strategy for AI-generated patterns: - Auto-warning at 500+ lines - Hard review at 600+ lines - Guidance: each 100 lines should add significant value Philosophy: Patterns should be scannable in 2-3 minutes with detailed implementations moved to examples/ directories. Addresses concern that AI can generate overly verbose patterns while maintaining "clarity over strict limits" philosophy. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 --- experiments/README.md | 2 +- pattern-spec.md | 29 +++++++++++++++++++++++++++++ 2 files changed, 30 insertions(+), 1 deletion(-) diff --git a/experiments/README.md b/experiments/README.md index 7f2815d..a7d540e 100644 --- a/experiments/README.md +++ b/experiments/README.md @@ -1143,7 +1143,7 @@ cat .ai/context-usage.log | grep -oE "rules/[^/]+/[^ ]+" | sort | uniq -c | sort - Split by clear domains: security/, development/, operations/ - Aim for 5-10 specialized files, not 50 -#### Anti-pattern: No Loading Guidance +#### Anti-pattern: Missing Guidance **Problem**: Creating specialized rule files but not telling the AI when to load them. diff --git a/pattern-spec.md b/pattern-spec.md index c04224d..eb23f72 100644 --- a/pattern-spec.md +++ b/pattern-spec.md @@ -224,6 +224,35 @@ Before finalizing an antipattern name, verify: - Provide specific consequences - Examples: "Manual Policy Translation", "Alert Fatigue", "Blind Chaos Testing" +### Pattern Length Guidelines + +**Recommended maximum lengths:** +- **Complete pattern**: 200-400 lines (target), 600 lines (max before splitting) +- **Description**: 1-2 sentences +- **Core implementation**: 150-300 lines +- **Individual anti-patterns**: 50-100 lines each +- **Code examples in README**: 30-50 lines max + +**When a pattern exceeds 600 lines:** +1. Review for unnecessary repetition or verbosity +2. Move detailed implementations to `examples/pattern-name/` directory +3. Consider splitting into multiple focused patterns +4. Remove "nice-to-have" scenarios that don't demonstrate core concepts + +**Philosophy**: Patterns should be **scannable in 2-3 minutes**. Readers should grasp the core concept quickly and reference examples/ for deep implementation details. + +**Enforcement Strategy** + +For AI-generated patterns: +1. **Auto-warning at 500+ lines**: "This pattern is getting long. Review for bloat." +2. **Hard review at 600+ lines**: "Consider splitting or moving detail to examples/" +3. **Guidance**: "Each additional 100 lines should add significant new value" + +**Quality over quantity:** +- ✅ 300 well-focused lines > 600 lines with repetition +- ✅ Clear core examples > exhaustive scenario coverage +- ✅ Scannable structure > comprehensive documentation + ## Formatting Standards ### Code Blocks From df90a22d4f22ff425b41fde858ac3fb850f7d3cf Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 11 Dec 2025 21:28:20 +0000 Subject: [PATCH 2/2] docs: fix anti-pattern naming for spec compliance MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Rename anti-patterns to use proper Negative + Noun format per pattern-spec.md: - "Constraint Overload" → "Over-Constrained" - "Secret Leakage" → "Leaked Secrets" - "Proving Impossibility" → "Unfounded Impossibility" - "Isolated Prompting" → "Disconnected Prompting" - "Overlapping Workspaces" → "Conflicting Workspaces" Updates README.md, experiments/README.md, examples, migration guide, and rename scripts for consistency. --- PATTERN_MIGRATION_GUIDE.md | 6 +++--- README.md | 6 +++--- experiments/README.md | 4 ++-- experiments/examples/asynchronous-research/README.md | 4 ++-- scripts/apply-pattern-renames.sh | 4 ++-- 5 files changed, 12 insertions(+), 12 deletions(-) diff --git a/PATTERN_MIGRATION_GUIDE.md b/PATTERN_MIGRATION_GUIDE.md index f4ce9e9..687fb1e 100644 --- a/PATTERN_MIGRATION_GUIDE.md +++ b/PATTERN_MIGRATION_GUIDE.md @@ -66,9 +66,9 @@ This change aligns with established pattern naming conventions: | Rushing Into AI | Premature Adoption | Added negative prefix | "Premature" clearly indicates timing failure | | Context Drift | Broken Context | Added negative prefix | "Broken" indicates failure state | | Unrestricted Access | Unrestricted Access | No change | Already compliant | -| Shared Agent Workspaces | Overlapping Workspaces | Changed to negative implication | "Overlapping" suggests conflict | +| Shared Agent Workspaces | Conflicting Workspaces | Changed to negative implication | "Conflicting" clearly indicates problem | | Ad-Hoc AI Development | Unplanned Development | Added negative prefix | "Unplanned" clearly negative | -| Prompt-Only AI Development | Isolated Prompting | Simplified, negative implication | "Isolated" suggests insufficient approach | +| Prompt-Only AI Development | Disconnected Prompting | Simplified, negative implication | "Disconnected" clearly indicates isolation from tools | | Vague Issue Generation | Under-Specified Issues | Added negative prefix | "Under-Specified" indicates insufficiency | | Missing CI Integration | Broken Integration | Added negative prefix | "Broken" indicates failure | | Implementation-First AI | Spec-Ignored | Symmetrical with "Spec-First" | Opposite of the pattern | @@ -80,7 +80,7 @@ This change aligns with established pattern naming conventions: | Knowledge Hoarding | Over-Documentation | Changed to "Over-" prefix | More technical description | | Context Bloat | Bloated Context | Adjusted word order | "Bloated" is negative adjective | | Unconstrained Generation | Unconstrained Generation | No change | Already compliant | -| Constraint Overload | Constraint Overload | No change | Already compliant | +| Constraint Overload | Over-Constrained | Changed to negative prefix | "Over-" prefix indicates excess | | Pseudo-Atomic Tasks | False Atomicity | Changed to "False" | More precise negative indicator | | Over-Decomposition | Over-Decomposition | No change | Already compliant | | Black Box Development | Blind Development | Changed "Black Box" to "Blind" | Simpler, maintains meaning | diff --git a/README.md b/README.md index a6ee23c..5851207 100644 --- a/README.md +++ b/README.md @@ -458,7 +458,7 @@ Modern AI development platforms provide enterprise-grade implementations of thes **Anti-pattern: Unrestricted Access** Allowing AI tools full system access risks credential leaks, data breaches, and security compliance violations. -**Anti-pattern: Overlapping Workspaces** +**Anti-pattern: Conflicting Workspaces** Allowing multiple parallel agents to write to the same directories creates race conditions, file conflicts, and unpredictable behavior that can corrupt the development environment. --- @@ -622,7 +622,7 @@ See [examples/tool-integration/](examples/tool-integration/) for: - Usage patterns and deployment guidelines - Integration with [Security Sandbox](#security-sandbox) -**Anti-pattern: Isolated Prompting** +**Anti-pattern: Disconnected Prompting** Attempting to solve complex data analysis, system integration, or real-time problems using only natural language prompts without providing AI access to actual data sources, APIs, or system tools. This leads to hallucinated responses, outdated information, and inability to interact with real systems. --- @@ -1372,7 +1372,7 @@ Good: "Reduce p99 latency to <50ms without new dependencies" **Anti-pattern: Unconstrained Generation** Giving AI vague instructions like "make it better" or "add features" leads to over-engineered solutions that are hard to maintain and review. -**Anti-pattern: Constraint Overload** +**Anti-pattern: Over-Constrained** Adding too many constraints ("use exactly 50 lines, 2 methods, no dependencies, 100% test coverage, sub-10ms response time") paralyzes AI decision-making and produces suboptimal solutions. --- diff --git a/experiments/README.md b/experiments/README.md index a7d540e..d3fcb6d 100644 --- a/experiments/README.md +++ b/experiments/README.md @@ -1451,7 +1451,7 @@ Simon's approach: - Mark repo as `noindex` for search engines - *"I still like to keep AI-generated content out of search, to avoid contributing more to the dead internet."* -#### Anti-pattern: Secret Leakage +#### Anti-pattern: Leaked Secrets **Problem**: Running unrestricted agents on production repos containing credentials. @@ -1459,7 +1459,7 @@ Simon warns: *"A prompt injection attack of the lethal trifecta variety could ea **Solution**: Only use unrestricted access on dedicated, secret-free research repos. -#### Anti-pattern: Proving Impossibility +#### Anti-pattern: Unfounded Impossibility **Problem**: Expecting agents to prove something can't be done. diff --git a/experiments/examples/asynchronous-research/README.md b/experiments/examples/asynchronous-research/README.md index f412770..096cdb7 100644 --- a/experiments/examples/asynchronous-research/README.md +++ b/experiments/examples/asynchronous-research/README.md @@ -373,13 +373,13 @@ python automation/result-parser.py research-folder/ **Solution**: Keep research in dedicated repo, mark as `noindex`. -### ❌ Secret Leakage +### ❌ Leaked Secrets **Problem**: Running unrestricted agents on repos with production secrets. **Solution**: Only use unrestricted access on dedicated, secret-free research repos. -### ❌ Proving Impossibility +### ❌ Unfounded Impossibility **Problem**: Expecting agents to prove something can't be done. diff --git a/scripts/apply-pattern-renames.sh b/scripts/apply-pattern-renames.sh index 0fc0513..a10d560 100755 --- a/scripts/apply-pattern-renames.sh +++ b/scripts/apply-pattern-renames.sh @@ -98,9 +98,9 @@ apply_renames() { # Antipattern Renames sed -i 's/\*\*Anti-pattern: Rushing Into AI\*\*/\*\*Anti-pattern: Premature Adoption\*\*/g' "$file" sed -i 's/\*\*Anti-pattern: Context Drift\*\*/\*\*Anti-pattern: Broken Context\*\*/g' "$file" - sed -i 's/\*\*Anti-pattern: Shared Agent Workspaces\*\*/\*\*Anti-pattern: Overlapping Workspaces\*\*/g' "$file" + sed -i 's/\*\*Anti-pattern: Shared Agent Workspaces\*\*/\*\*Anti-pattern: Conflicting Workspaces\*\*/g' "$file" sed -i 's/\*\*Anti-pattern: Ad-Hoc AI Development\*\*/\*\*Anti-pattern: Unplanned Development\*\*/g' "$file" - sed -i 's/\*\*Anti-pattern: Prompt-Only AI Development\*\*/\*\*Anti-pattern: Isolated Prompting\*\*/g' "$file" + sed -i 's/\*\*Anti-pattern: Prompt-Only AI Development\*\*/\*\*Anti-pattern: Disconnected Prompting\*\*/g' "$file" sed -i 's/\*\*Anti-pattern: Vague Issue Generation\*\*/\*\*Anti-pattern: Under-Specified Issues\*\*/g' "$file" sed -i 's/\*\*Anti-pattern: Missing CI Integration\*\*/\*\*Anti-pattern: Broken Integration\*\*/g' "$file" sed -i 's/\*\*Anti-pattern: Implementation-First AI\*\*/\*\*Anti-pattern: Spec-Ignored\*\*/g' "$file"