feat(rules): add enterprise-patterns rule covering Fowler PEAA (#1753)#1762
Merged
Conversation
Add `.claude/rules/enterprise-patterns.md` (~11KB) covering Repository, Unit of Work, Data Mapper, Service Layer, and Identity Map patterns from Martin Fowler's Patterns of Enterprise Application Architecture. The rule reinforces patterns the codebase already uses implicitly so workers extend existing seams (orchestrator, session management, memory systems) rather than introduce competing abstractions. Frontmatter sets alwaysApply false; the rule is agent-requestable when persistence, transactional, or orchestration code changes. Add session log per ADR-007 / SESSION-PROTOCOL. Fixes #1753 Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Contributor
PR Validation ReportTip ✅ Status: PASS Description Validation
PR Standards
QA Validation
Powered by PR Validation workflow |
Contributor
Session Protocol Compliance ReportTip ✅ Overall Verdict: PASS All session protocol requirements satisfied. What is Session Protocol?Session logs document agent work sessions and must comply with RFC 2119 requirements:
See Compliance Summary
Detailed Validation ResultsClick each session to see the complete validation report with specific requirement failures. 📄 sessions-2026-04-25-session-1753-enterprise-patterns-rules=== Session Validation === [PASS] Session log is valid ✨ Zero-Token ValidationThis validation uses deterministic script analysis instead of AI:
Powered by 📊 Run Details
Powered by Session Protocol Validator workflow |
Contributor
AI Quality Gate ReviewWarning WalkthroughThis PR was reviewed by six AI agents in parallel, analyzing different aspects of the changes:
Review Summary
💡 Quick Access: Click on individual agent jobs (e.g., "🔒 security Review", "🧪 qa Review") in the workflow run to see detailed findings and step summaries. Security Review DetailsSecurity Review: PR #1762PR Type Classification
This is a DOCS + CONFIG PR containing architectural documentation and a session log. Findings
Analysis
RecommendationsNone required. Verdict{
"verdict": "PASS",
"message": "Documentation-only PR adding enterprise architecture patterns guidance. No security-relevant code or sensitive data.",
"agent": "security",
"timestamp": "2026-04-25T12:25:16.093Z",
"findings": []
}QA Review DetailsNow I have all the information needed to complete the QA review. QA Review: PR #1762PR Type ClassificationTest Coverage AssessmentN/A - This PR contains only documentation (markdown rule file) and configuration (session log JSON). No executable code is added or modified. Pre-executed pytest results confirm: 7098 passed, 3 skipped. No test regressions from this PR. Quality Concerns
Regression Risk Assessment
Documentation QualityThe markdown rule file is well-structured:
No broken links detected. No syntax errors in content. VERDICT: WARN MESSAGE: Documentation PR is sound but session log contains invalid placeholder values that violate JSON schema. PR TYPE: MIXED (DOCS + CONFIG) EVIDENCE:
The session log {
"verdict": "WARN",
"message": "Documentation PR is sound but session log contains invalid placeholder values that violate JSON schema",
"agent": "qa",
"timestamp": "2026-04-25T12:26:25.986Z",
"findings": [
{
"severity": "medium",
"category": "code-quality",
"description": "Session log endingCommit field contains 'pending' which violates schema pattern requiring empty string or 7-40 char hex SHA",
"location": ".agents/sessions/2026-04-25-session-1753-enterprise-patterns-rules.json:147",
"recommendation": "Update to empty string or actual commit SHA"
},
{
"severity": "medium",
"category": "code-quality",
"description": "Session log prUrl field contains placeholder 'pending' instead of actual PR URL",
"location": ".agents/sessions/2026-04-25-session-1753-enterprise-patterns-rules.json:148",
"recommendation": "Update to actual PR URL or remove field"
},
{
"severity": "low",
"category": "code-quality",
"description": "Session log missing recommended schemaVersion field",
"location": ".agents/sessions/2026-04-25-session-1753-enterprise-patterns-rules.json",
"recommendation": "Add schemaVersion: '1.0' for migration compatibility"
}
]
}Analyst Review DetailsNow I have enough context to complete the analysis. Code Quality Score
Overall: 5/5 Impact Assessment
Findings
Recommendations
Verdict{
"verdict": "WARN",
"message": "Session log contains 'pending' placeholders violating schema pattern; rule content meets spec requirements.",
"agent": "analyst",
"timestamp": "2026-04-25T12:25:16Z",
"findings": [
{
"severity": "medium",
"category": "consistency",
"description": "endingCommit value 'pending' violates schema pattern ^([0-9a-f]{7,40})?$",
"location": ".agents/sessions/2026-04-25-session-1753-enterprise-patterns-rules.json:145",
"recommendation": "Replace with empty string or valid 7-40 char lowercase hex SHA"
},
{
"severity": "medium",
"category": "consistency",
"description": "prUrl value 'pending' is non-standard placeholder",
"location": ".agents/sessions/2026-04-25-session-1753-enterprise-patterns-rules.json:146",
"recommendation": "Replace with empty string or valid URL once PR is created"
},
{
"severity": "low",
"category": "documentation",
"description": "alwaysApply: false rationale documented in PR but not in file",
"location": ".claude/rules/enterprise-patterns.md:3",
"recommendation": "Optional: add brief comment in frontmatter or opening paragraph"
}
]
}Architect Review DetailsI see the issue. The session log has Design Quality Assessment
Overall Design Score: 5/5 Architectural Concerns
Breaking Change Assessment
Technical Debt Analysis
ADR Assessment
Recommendations
VerdictThe rule file is well-structured and follows established patterns. The content accurately describes PEAA patterns with clear application guidance specific to the ai-agents codebase. The {
"verdict": "WARN",
"message": "Session log uses invalid placeholder values for endingCommit and prUrl fields; rule content is architecturally sound.",
"agent": "architect",
"timestamp": "2026-04-25T12:25:23.063Z",
"findings": [
{
"severity": "low",
"category": "tech-debt",
"description": "endingCommit field contains 'pending' which violates schema pattern ^([0-9a-f]{7,40})?$",
"location": ".agents/sessions/2026-04-25-session-1753-enterprise-patterns-rules.json:148",
"recommendation": "Replace 'pending' with empty string or actual commit SHA"
},
{
"severity": "low",
"category": "tech-debt",
"description": "prUrl field contains 'pending' which should be empty string or valid URL",
"location": ".agents/sessions/2026-04-25-session-1753-enterprise-patterns-rules.json:149",
"recommendation": "Replace 'pending' with empty string or actual PR URL after creation"
}
]
}DevOps Review DetailsDevOps Review: PR #1762PR Scope Detection
Classification: DOCS + CONFIG (session log JSON). No CI/CD, workflow, or infrastructure changes. Pipeline Impact Assessment
CI/CD Quality Checks
Findings
Note: The Template Assessment
Automation OpportunitiesNone identified. This is a content-only documentation change. Recommendations
Verdict{
"verdict": "PASS",
"message": "Documentation-only PR with no CI/CD impact",
"agent": "devops",
"timestamp": "2026-04-25T12:25:20.851Z",
"findings": [
{
"severity": "low",
"category": "artifacts",
"description": "Session log contains 'pending' placeholder for endingCommit and prUrl instead of actual values",
"location": ".agents/sessions/2026-04-25-session-1753-enterprise-patterns-rules.json:147-148",
"recommendation": "Update to actual commit SHA and PR URL; does not block merge"
}
]
}Roadmap Review DetailsStrategic Alignment Assessment
Feature Completeness
Impact Analysis
Concerns
Recommendations
Verdict{
"verdict": "PASS",
"message": "Enterprise patterns rule aligns with multi-agent consistency goals, right-sized scope, and low maintenance burden.",
"agent": "roadmap",
"timestamp": "2026-04-25T12:25:19.414Z",
"findings": [
{
"severity": "low",
"category": "documentation",
"description": "Session log contains placeholder values for endingCommit and prUrl",
"location": ".agents/sessions/2026-04-25-session-1753-enterprise-patterns-rules.json:149-150",
"recommendation": "Update to actual commit SHA and PR URL before merge"
}
]
}Run Details
Powered by AI Quality Gate workflow |
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Repository YAML (base), Organization UI (inherited) Review profile: CHILL Plan: Pro Run ID: ⛔ Files ignored due to path filters (1)
📒 Files selected for processing (1)
📝 WalkthroughWalkthroughNew Claude rules document added consolidating PEAA enterprise architecture patterns including Repository, Unit of Work, Data Mapper, Service Layer, and Identity Map. Document specifies pattern usage rules, boundaries, transaction scope, identity caching, mapping responsibilities, service orchestration flow, anti-patterns, and includes a pre-change checklist. Changes
Estimated code review effort🎯 1 (Trivial) | ⏱️ ~5 minutes Suggested labels
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
Contributor
There was a problem hiding this comment.
Code Review
This pull request introduces a new rule file, .claude/rules/enterprise-patterns.md, which defines enterprise architecture patterns such as Repository, Unit of Work, and Service Layer for the codebase. The review feedback focuses on ensuring the documentation adheres to the project's style guide, specifically regarding maximum sentence length, the use of active voice, and addressing the user directly as 'you'.
|
|
||
| # Enterprise Patterns | ||
|
|
||
| This rule consolidates the patterns from Martin Fowler's _Patterns of Enterprise Application Architecture_ (PEAA) that recur in this codebase. Use it when you change persistence, transactional, or orchestration code, or when you introduce a new component that touches a data store, an external service, or a long-running workspace. |
Contributor
There was a problem hiding this comment.
This sentence exceeds the maximum length of 25 words (34 words) and combines multiple ideas. Break it into shorter, focused sentences to improve readability and adhere to the style guide.
Suggested change
| This rule consolidates the patterns from Martin Fowler's _Patterns of Enterprise Application Architecture_ (PEAA) that recur in this codebase. Use it when you change persistence, transactional, or orchestration code, or when you introduce a new component that touches a data store, an external service, or a long-running workspace. | |
| This rule consolidates the patterns from Martin Fowler's Patterns of Enterprise Application Architecture (PEAA) that recur in this codebase. Use it when changing persistence, transactional, or orchestration code. Also apply it when introducing components touching data stores, external services, or long-running workspaces. |
References
- Sentences must not exceed 25 words and should convey one idea. (link)
|
|
||
| This rule consolidates the patterns from Martin Fowler's _Patterns of Enterprise Application Architecture_ (PEAA) that recur in this codebase. Use it when you change persistence, transactional, or orchestration code, or when you introduce a new component that touches a data store, an external service, or a long-running workspace. | ||
|
|
||
| The codebase already uses several of these patterns implicitly. Make them explicit in new code rather than create competing shapes (for example, a second class that loads the same entity through a different path). When in doubt, find the existing collaborator and extend it. |
Contributor
There was a problem hiding this comment.
This sentence exceeds the maximum length of 25 words (27 words). Break it into shorter sentences to comply with the style guide.
Suggested change
| The codebase already uses several of these patterns implicitly. Make them explicit in new code rather than create competing shapes (for example, a second class that loads the same entity through a different path). When in doubt, find the existing collaborator and extend it. | |
| The codebase already uses several of these patterns implicitly. Make them explicit in new code. Avoid creating competing shapes, such as a second class loading the same entity through a different path. When in doubt, find the existing collaborator and extend it. |
References
- Sentences must not exceed 25 words. (link)
| - Methods read like collection operations: `add`, `remove`, `find...`, `exists`. Do not name them after SQL verbs. | ||
| - Each domain aggregate has at most one repository. If you find yourself writing a second repository for the same aggregate, you are usually missing a query method on the first one. | ||
| - Repositories do not commit. Commits belong to the Unit of Work or the calling Service Layer. | ||
| - Filtering and projection live behind named methods. Avoid passing predicates or query objects across the boundary unless you have a Specification pattern in place and the caller actually composes them. |
Contributor
There was a problem hiding this comment.
This sentence exceeds the maximum length of 25 words (28 words).
Suggested change
| - Filtering and projection live behind named methods. Avoid passing predicates or query objects across the boundary unless you have a Specification pattern in place and the caller actually composes them. | |
| - Filtering and projection live behind named methods. Avoid passing predicates or query objects across the boundary. Only do this if a Specification pattern exists and the caller composes them. |
References
- Sentences must not exceed 25 words. (link)
| - Track three sets explicitly: new, dirty, and removed. Resolve order at commit time so callers do not have to think about it. | ||
| - Commit at the boundary of the use case, not inside repositories or domain methods. | ||
| - On failure, roll back and surface the failure. Never partially commit. Never swallow the error and continue. | ||
| - A Unit of Work is short-lived. If yours spans HTTP requests, agent turns, or user interactions, you are using it for caching; use an Identity Map for that instead. |
Contributor
There was a problem hiding this comment.
This sentence exceeds the maximum length of 25 words (26 words).
Suggested change
| - A Unit of Work is short-lived. If yours spans HTTP requests, agent turns, or user interactions, you are using it for caching; use an Identity Map for that instead. | |
| - A Unit of Work is short-lived. If yours spans HTTP requests, agent turns, or user interactions, you are using it for caching. Use an Identity Map instead. |
References
- Sentences must not exceed 25 words. (link)
| - Services depend on abstractions. Inject repositories and external clients; do not new them up inline. | ||
| - A Service method should be short. If it grows past a screen, the use case is doing too much; split it into a domain method or a smaller service. | ||
|
|
||
| In ai-agents, the agent orchestrator is the canonical Service Layer. New use cases that coordinate repositories, sessions, or external tools belong there or in a sibling service, not scattered across hooks and skills. |
Contributor
There was a problem hiding this comment.
The second sentence exceeds the maximum length of 25 words (26 words) and uses passive voice ("scattered"). Use active voice with clear actors.
Suggested change
| In ai-agents, the agent orchestrator is the canonical Service Layer. New use cases that coordinate repositories, sessions, or external tools belong there or in a sibling service, not scattered across hooks and skills. | |
| In ai-agents, the agent orchestrator is the canonical Service Layer. New use cases coordinating repositories, sessions, or external tools belong there or in a sibling service. Do not scatter them across hooks and skills. |
References
- Sentences must not exceed 25 words. Use active voice with clear actors. (link)
| - **Repository as DAO**: methods named `executeQuery`, `runUpdate`, or `getConnection`. Replace with named, intention-revealing operations. | ||
| - **Ambient transactions**: a global or thread-local `currentTransaction()` that any code may read or write. Pass the Unit of Work explicitly. | ||
| - **Cross-aggregate transactions stretched across services**: do not paper over a missing aggregate boundary with a longer transaction. Redraw the boundary. | ||
| - **Pattern stacking**: every read goes through five layers because "the patterns say so." If a layer never varies and never gets tested in isolation, delete it. |
Contributor
There was a problem hiding this comment.
This sentence uses passive voice ("gets tested"). The style guide requires active voice with clear actors performing the action.
Suggested change
| - **Pattern stacking**: every read goes through five layers because "the patterns say so." If a layer never varies and never gets tested in isolation, delete it. | |
| - Pattern stacking: every read goes through five layers because "the patterns say so." If a layer never varies and you never test it in isolation, delete it. |
References
- Use active voice with clear actors performing the action. (link)
| - Skills and hooks are entry points. Keep them thin: parse inputs, call a service, format output. They are not the place for business rules. | ||
| - Memory systems (Serena, Forgetful) act as Repositories of long-lived knowledge. Do not bypass them with direct file reads when the named operation already exists. | ||
|
|
||
| When you find a place where the codebase deviates from this rule, prefer a small focused refactor on the path you are already touching over a large rewrite. Note the deviation in the PR description so future readers see your reasoning. |
Contributor
There was a problem hiding this comment.
The first sentence exceeds the maximum length of 25 words (31 words).
Suggested change
| When you find a place where the codebase deviates from this rule, prefer a small focused refactor on the path you are already touching over a large rewrite. Note the deviation in the PR description so future readers see your reasoning. | |
| When the codebase deviates from this rule, prefer a small focused refactor on the current path. Avoid large rewrites. Note the deviation in the PR description so future readers see your reasoning. |
References
- Sentences must not exceed 25 words. (link)
| - Does the code touch a data store directly, or through a repository? | ||
| - If it changes more than one aggregate, is there exactly one Unit of Work that commits the whole change? | ||
| - Do domain objects depend on persistence types, or only on other domain types? | ||
| - Is the use case named, single-purpose, and visible at the Service Layer? |
Contributor
There was a problem hiding this comment.
This sentence uses passive voice ("named"). Use active voice to improve clarity.
Suggested change
| - Is the use case named, single-purpose, and visible at the Service Layer? | |
| - Does the use case have a name, a single purpose, and visibility at the Service Layer? |
References
- Use active voice with clear actors. (link)
| - If it changes more than one aggregate, is there exactly one Unit of Work that commits the whole change? | ||
| - Do domain objects depend on persistence types, or only on other domain types? | ||
| - Is the use case named, single-purpose, and visible at the Service Layer? | ||
| - Could the same entity be loaded twice in this operation? If yes, is the Identity Map handling that? |
Contributor
There was a problem hiding this comment.
This sentence uses passive voice ("be loaded"). Use active voice and address the user as "you".
Suggested change
| - Could the same entity be loaded twice in this operation? If yes, is the Identity Map handling that? | |
| - Could you load the same entity twice in this operation? If yes, is the Identity Map handling that? |
References
- Use active voice and address the user as 'you'. (link)
This was referenced Apr 25, 2026
Merged
rjmurillo
pushed a commit
that referenced
this pull request
Apr 26, 2026
Resolves conflict in .github/workflows/pytest.yml. Both branches added --ignore-vuln CVE-2026-3219 to pip-audit (this branch in aee5278, main in #1779). Took main's version since #1779 has the canonical, more detailed rationale comment block (links to pypa/pip#13870 fix PR, explains the local-only attack surface and why it does not apply to CI). Also addresses the latest Copilot review comments on this PR: - tests/eval/test_eval_prompt_change.py: scope the sys.path mutation to module load only and restore it in a finally block. eval-prompt- change.py imports sibling modules (_anthropic_api, _eval_common) by bare name, so EVAL_DIR must be on sys.path during exec_module(); removing the entry afterwards prevents the addition from leaking into other tests' import resolution. Tests still pass: 85 in this file, 107 with workspace-limits tests included. - .agents/sessions/2026-04-25-session-1714.json: rewrite workLog steps 1 and 7 evidence so they no longer reference .agents/audit/eval-1741/ or .agents/audit/eval-1755/ paths that do not exist in the repo (the artifacts were transient and dropped in 31ed283). Step 1 now points to the reproducer command; step 7 points to the per-agent table in the PR Honesty notes section. Pulls in main's PR #1779 (pip CVE ignore w/ rationale) and PR #1762 (enterprise-patterns rule) as part of the merge. Refs #1755 Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> https://claude.ai/code/session_01XALNMgBrrH7Ya8dM1CjYzo
rjmurillo
pushed a commit
that referenced
this pull request
Apr 26, 2026
Adds .claude/rules/refactoring.md following the established .claude/rules/ pattern (mirrors merged enterprise-patterns.md from PR #1762). Encodes the discipline from Martin Fowler's Refactoring so reviewers can tell whether a change is structure, behavior, or both. Covers all six items the issue lists as required: - Refactoring preserves observable behavior - Behavior changes stay separate from structural cleanup (two-hat rule) - Small, named, mechanical transformations only (no big-bang rewrites) - Tests must pass between every step - Code-smell triggers (long function, feature envy, shotgun surgery, plus 14 more) - No refactor + feature in the same commit Integrates with ADR-008 commit budget and atomic-commit file limit explicitly. Boundaries section ties the rule to the existing enterprise-patterns.md (target shapes) and the session protocol (evidence). Fixes #1746 Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
rjmurillo
pushed a commit
that referenced
this pull request
Apr 26, 2026
…niques (#1747) Encode Michael Feathers' techniques from Working Effectively with Legacy Code as a conditional Claude rule. Activates when the file under change has low test coverage, is older than six months, or is on a To Improve fix cycle from the auto-escalation ladder. Covers characterization tests, seams (object, link, build), sprout method/class, wrap method/class, dependency-breaking techniques (extract interface, parameterize constructor, introduce instance delegator, subclass and override, pull up dependency), and the hard rule never to delete failing tests to make a refactor pass. Mirrors the structure and frontmatter of .claude/rules/enterprise-patterns.md introduced in #1762. Fixes #1747 Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
rjmurillo
pushed a commit
that referenced
this pull request
Apr 26, 2026
…ut APoSD (#1748) Adds .claude/rules/philosophy-of-software-design.md encoding John Ousterhout's heuristics from "A Philosophy of Software Design": deep modules, information hiding, complexity symptoms (change amplification, cognitive load, unknown unknowns), pull complexity downward, define errors out of existence, design it twice, comments-describe-what-code-cannot, strategic vs tactical. Includes a Boundaries with Existing Codebase section that ties the rule to ai-agents tool/skill interfaces, agent prompts, plugin seams, hooks, and memory systems so workers reuse existing seams instead of introducing parallel ones. Mirrors the structural conventions of .claude/rules/enterprise-patterns.md (PR #1762). Fixes #1748 Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
rjmurillo
pushed a commit
that referenced
this pull request
Apr 26, 2026
…rinciples (#1750) Fixes #1750 Adds .claude/rules/pragmatic-programmer.md as a binding engineering policy applied as a general overlay for all worker agents. Source content adapted from ciembor/agent-rules-books (MIT) at the-pragmatic-programmer/claude/.claude/rules/the-pragmatic-programmer.md. Covers DRY at the knowledge level, orthogonality, tracer-bullet delivery, prototyping discipline, automation, fast feedback loops, design by contract, error handling, naming and communication, text and data, state and concurrency, estimation, tooling, broken-windows discipline, forbidden patterns, code generation defaults, testing rules, and a pre-merge review checklist. Adds a Multi-Agent Context section that maps each principle to ai-agents agent, skill, and hook boundaries — DRY at knowledge level for cross-prompt policy, orthogonality across agents, tracer bullets for new agent capabilities, broken windows for stale prompts, automation in hooks instead of prose, and short-feedback signals. Mirrors the frontmatter schema established by sibling PR #1762 (issue #1753, enterprise-patterns.md). alwaysApply set to true because pragmatic principles are everyday engineering overlay, unlike enterprise-patterns which is conditional. markdownlint-cli2 confirms zero violations from the new file. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
rjmurillo
pushed a commit
that referenced
this pull request
Apr 26, 2026
Adds .claude/rules/clean-architecture.md (~15KB) encoding Robert C. Martin's Clean Architecture for this codebase: dependency rule, entities, use cases, interface adapters, frameworks and drivers, boundary protection, pattern selection, anti-patterns, and a quick self-review. The Boundaries section ties the rule to existing ai-agents seams: the orchestrator and lifecycle skills as use cases, GitHub and MCP wrappers as interface adapters, GitHub Actions/gh/MCP servers as frameworks. Reinforces, not duplicates, AGENTS.md guidance. alwaysApply: false because the rule is conditional, applied when boundary-crossing changes are in flight, not on every edit. Refs PR #1762 (enterprise-patterns) for the established .claude/rules/ pattern; this change matches that schema and adds a session log under .agents/sessions/. Fixes #1749 Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
rjmurillo-bot
added a commit
that referenced
this pull request
Apr 26, 2026
…1775) * feat(rules): add refactoring rule covering Fowler discipline (#1746) Adds .claude/rules/refactoring.md following the established .claude/rules/ pattern (mirrors merged enterprise-patterns.md from PR #1762). Encodes the discipline from Martin Fowler's Refactoring so reviewers can tell whether a change is structure, behavior, or both. Covers all six items the issue lists as required: - Refactoring preserves observable behavior - Behavior changes stay separate from structural cleanup (two-hat rule) - Small, named, mechanical transformations only (no big-bang rewrites) - Tests must pass between every step - Code-smell triggers (long function, feature envy, shotgun surgery, plus 14 more) - No refactor + feature in the same commit Integrates with ADR-008 commit budget and atomic-commit file limit explicitly. Boundaries section ties the rule to the existing enterprise-patterns.md (target shapes) and the session protocol (evidence). Fixes #1746 Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * fix(rules): correct commit budget references in refactoring rule ADR-008 covers SESSION-PROTOCOL lifecycle hooks, not commit budgets. Point readers to CONTRIBUTING.md for the 20-commit PR limit and to AGENTS.md for the atomic commits per-file (<=5 files) budget so the refactoring rule cites the actual sources of truth. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> --------- Co-authored-by: rjmurillo-bot <rjmurillo-bot@users.noreply.github.com> Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com> Co-authored-by: Test <test@test.com>
rjmurillo-bot
added a commit
that referenced
this pull request
Apr 26, 2026
…r bullets) (#1750) (#1764) * feat(rules): add pragmatic-programmer rule covering Hunt and Thomas principles (#1750) Fixes #1750 Adds .claude/rules/pragmatic-programmer.md as a binding engineering policy applied as a general overlay for all worker agents. Source content adapted from ciembor/agent-rules-books (MIT) at the-pragmatic-programmer/claude/.claude/rules/the-pragmatic-programmer.md. Covers DRY at the knowledge level, orthogonality, tracer-bullet delivery, prototyping discipline, automation, fast feedback loops, design by contract, error handling, naming and communication, text and data, state and concurrency, estimation, tooling, broken-windows discipline, forbidden patterns, code generation defaults, testing rules, and a pre-merge review checklist. Adds a Multi-Agent Context section that maps each principle to ai-agents agent, skill, and hook boundaries — DRY at knowledge level for cross-prompt policy, orthogonality across agents, tracer bullets for new agent capabilities, broken windows for stale prompts, automation in hooks instead of prose, and short-feedback signals. Mirrors the frontmatter schema established by sibling PR #1762 (issue #1753, enterprise-patterns.md). alwaysApply set to true because pragmatic principles are everyday engineering overlay, unlike enterprise-patterns which is conditional. markdownlint-cli2 confirms zero violations from the new file. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * ci: trigger validation re-run with bypass label * docs(rules): address review feedback on pragmatic-programmer - Inline the engineering-qualities guidance instead of referencing .claude/skills/golden-principles/. Project policy requires agent templates to be self-contained without external file paths (CodeRabbit major finding). - Reword the prototyping rule to drop the "pretend you are done" phrasing that triggered a Semgrep skill-roleplay-persona-attack false positive. Meaning is unchanged: a prototype is for learning, not a substitute for finished work. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> --------- Co-authored-by: rjmurillo-bot <rjmurillo-bot@users.noreply.github.com> Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com> Co-authored-by: Test <test@test.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Pull Request
Summary
Adds
.claude/rules/enterprise-patterns.md(~11KB) covering five patterns from Martin Fowler's Patterns of Enterprise Application Architecture (PEAA) that recur in this codebase: Repository, Unit of Work, Data Mapper, Service Layer, and Identity Map. The rule reinforces patterns the codebase already uses implicitly so workers extend existing seams rather than introduce competing abstractions.Specification References
Changes
.claude/rules/enterprise-patterns.mdwith frontmatter (description,alwaysApply: false) and sections: Core Vocabulary, Repository, Unit of Work, Data Mapper, Service Layer, Identity Map, Pattern Selection, Anti-Patterns, Boundaries with Existing Codebase, Quick Self-Review..agents/sessions/2026-04-25-session-1753-enterprise-patterns-rules.jsonper ADR-007 / SESSION-PROTOCOL.alwaysApply: falseis intentional. Unlikecode-quality(everyday fundamentals applied on every edit), enterprise patterns are situational. The description lets agents pull the rule when persistence, transactional, or orchestration code changes.Type of Change
Testing
markdownlint-cli2 .claude/rules/enterprise-patterns.mdreports zero new errors. The 21 errors reported by repo-wide lint are pre-existing in unrelated agent template files.python3 -c "import json; json.load(open(...))".Agent Review
Security Review
Other Agent Reviews
Checklist
Related Issues
Fixes #1753