[FEATURE] User-Level Agent Rules and Rule Propagation

[baslogic]

Preflight Checklist

• I have searched existing requests and this feature hasn't been requested yet
• This is a single feature request (not multiple features)

Problem Statement

The Problem

As a Claude Code user working with multiple subagents, I need a way to define user-level rules and preferences that can be consistently applied across my primary agent and optionally propagated to subagents. Currently, there is no documented mechanism to:

1. Define user-level rules that apply specifically to the primary Claude Code agent
2. Propagate user-level rules or instructions down to subagents
3. Control which rules should apply to which agents in the hierarchy

Why This Is Needed

Workflow Context:

I'm building a "subagent army" - multiple specialized subagents for different tasks (documentation, testing, code review, etc.). I need certain rules to apply consistently across all agents, while other rules should only apply to the primary agent.

Current Pain Points:

1. No centralized rule management: I must manually copy rules into every subagent's configuration file
2. Inconsistent behavior: Each subagent operates in isolation without awareness of my preferences
3. Maintenance nightmare: When I want to change a rule, I need to update 10+ subagent files
4. No separation of concerns: Can't differentiate between UI-specific rules (primary only) and behavioral rules (all agents)

Real-World Impact:

When the primary agent delegates to a subagent, the subagent doesn't follow my coding style preferences, response format rules, or proactive behavior guidelines. This breaks my workflow and requires constant manual intervention to maintain consistency.

Discovery of the Gap

I attempted to create ~/.claude/primary-agent-rules.md expecting it to work like CLAUDE.md but at the user level. The file was never loaded. Investigation of the official documentation revealed:

• No mechanism exists for user-level agent instruction files
• Subagents operate in isolated contexts with their own system prompts
• No documented way to inherit or propagate rules from primary to subagents
• Official configuration is limited to project-level (CLAUDE.md) or settings (settings.json)

This isn't just a documentation gap - the feature doesn't exist.

Proposed Solution

2. Proposed Solution

Ideal User Experience

Step 1: Create User-Level Rules File

I create ~/.claude/primary-agent-rules.md in my home directory:

# Primary Agent Rules

**SCOPE: These rules apply to the primary Claude Code agent.**

## Response Format Rules
- Append 🔵 at end of every response (for UI tracking)
- Always use Oxford commas in lists

## Proactive Behavior Rules
- Use hello-world-agent when user says "hi cc"
- Use documentation-specialist for any .md file creation

What happens: Claude Code automatically loads this file when the primary agent starts.

Step 2: Define Shared Rules for All Agents

I create ~/.claude/agent-rules.md for rules that should propagate:

# Shared Agent Rules

**SCOPE: These rules apply to ALL agents (primary and subagents).**

## Code Style
- Use single quotes for strings in JavaScript
- Maximum line length: 100 characters
- Always include JSDoc comments for functions

## Git Commit Style
- Use conventional commits format
- First line max 50 characters
- Include ticket number in commit message

What happens: All subagents automatically receive these rules when invoked.

Step 3: Configure Rule Propagation (Optional)

If I need fine-grained control, I can configure in ~/.claude/settings.json:

{
  "agentRules": {
    "primaryRulesFile": "~/.claude/primary-agent-rules.md",
    "sharedRulesFile": "~/.claude/agent-rules.md",
    "propagateToSubagents": true,
    "allowSubagentOverride": false
  }
}

Step 4: Subagent-Specific Overrides (Optional)

For specific subagents that need different rules, I can configure in the subagent's YAML frontmatter:

---
name: code-reviewer
description: Reviews code for quality
inherit_rules: true              # Inherit from agent-rules.md
custom_rules: ~/.claude/reviewer-specific-rules.md  # Additional rules
---

You are a code reviewer specializing in security vulnerabilities.

How I'd Interact With This Feature

Daily workflow:

1. Start working on a project
2. Primary agent loads my primary-agent-rules.md automatically - I see the 🔵 marker at the end of responses
3. I ask primary agent to create documentation - it automatically uses documentation-specialist subagent
4. The subagent follows my code style rules from agent-rules.md without me specifying them
5. When subagent reports back, it doesn't include the 🔵 marker (primary-only rule)

When I need to change a rule:

1. Edit ~/.claude/agent-rules.md once
2. All future subagents automatically use the new rule
3. No need to update 10+ individual subagent configurations

Alternative Solutions

3. Alternative Solutions

Workarounds Tried

Workaround 1: Manual System Prompt Instructions

Approach: Add instruction to each subagent's system prompt to read the rules file:

---
name: my-subagent
description: Does something
---

IMPORTANT: Before responding, read and follow rules in ~/.claude/primary-agent-rules.md

[Rest of system prompt...]

Limitations:

• ❌ Must manually add to every subagent (currently 12 subagents, growing)
• ❌ No guarantee subagents actually read the file
• ❌ Requires File Read tool access for every subagent
• ❌ If I forget to add this instruction, rules aren't followed
• ❌ Can't differentiate primary-only vs shared rules

Why this doesn't work: Not scalable, error-prone, and relies on subagent cooperation rather than system enforcement.

Workaround 2: Project-Level CLAUDE.md

Approach: Add conditional instructions in CLAUDE.md:

# Agent Rules

If you are a subagent, follow these rules:
- Rule 1
- Rule 2

Limitations:

• ❌ CLAUDE.md is project-level, not user-level (doesn't work across all my projects)
• ❌ Unknown if CLAUDE.md content is even available to subagents (undocumented)
• ❌ Mixes project-specific instructions with user-level preferences
• ❌ Each project needs its own copy of my user preferences

Why this doesn't work: I need user-level rules that apply across all projects I work on, not per-project configuration.

Workaround 3: Settings.json with JSON-Encoded Rules

Approach: Store rules as strings in settings.json:

{
  "customInstructions": {
    "primary": "Append 🔵 at end of responses",
    "shared": "Use single quotes for JavaScript strings"
  }
}

Limitations:

• ❌ Not documented as a supported feature (doesn't actually work)
• ❌ JSON is terrible for long-form instructions
• ❌ No Markdown formatting support
• ❌ Harder to read and maintain than dedicated .md files

Why this doesn't work: JSON isn't designed for long-form instructions, and this isn't a documented feature anyway.

Current Working Solution (Painful)

I maintain a template file and manually copy-paste rules into each subagent configuration when I create it. When rules change, I use find/replace across all files. This is error-prone and doesn't scale.

Priority

Critical - Blocking my work

Feature Category

CLI commands and flags

Use Case Example

4. Use Case Example

Scenario: Managing Code Style Consistency Across Multiple Agents

Context: I'm working on a large TypeScript project with strict coding standards. I use multiple specialized subagents:

• code-reviewer: Reviews PRs for quality issues
• test-writer: Writes unit tests
• documentation-specialist: Creates/updates documentation
• refactoring-agent: Refactors code for better architecture
• bug-fixer: Fixes reported bugs

The Problem: Each subagent generates code in slightly different styles because they don't share my coding preferences.

Step-by-Step Walkthrough

Step 1: Initial State (Current Behavior)

I ask primary agent: "Review this PR, add tests, and update docs"

Primary agent delegates to 3 subagents:

1. code-reviewer reviews code (✅ works fine, just analysis)
2. test-writer creates tests with double quotes: expect("result").toBe("expected")
3. documentation-specialist creates docs with different code style

Problem: Test code and docs don't match my style guide (single quotes, specific comment format).

Step 2: With Proposed Feature

I create ~/.claude/agent-rules.md:

# Shared Agent Rules

## TypeScript Code Style
- Use single quotes for strings
- Use 2-space indentation
- Always include JSDoc comments with @param and @returns
- Prefer const over let
- Use arrow functions for callbacks

## Git Commits
- Use conventional commits: feat:, fix:, docs:, refactor:
- Include JIRA ticket number: [PROJ-123]
- First line max 50 chars, body max 72 chars per line

## Documentation Style
- Use TypeScript code examples, not JavaScript
- Include "Example" and "Returns" sections
- Cross-reference related functions with links

I configure ~/.claude/settings.json:

{
  "agentRules": {
    "sharedRulesFile": "~/.claude/agent-rules.md",
    "propagateToSubagents": true
  }
}

Step 3: New Behavior

I ask primary agent: "Review this PR, add tests, and update docs"

Primary agent delegates to 3 subagents, ALL of which automatically receive my agent-rules.md:

1. code-reviewer analyzes code (no code generation, rules not needed but harmless)
2. test-writer creates tests with single quotes: expect('result').toBe('expected')
3. documentation-specialist creates docs with TypeScript examples and proper formatting

Result: All generated code follows my style guide automatically. No manual intervention needed.

Step 4: Making Changes

Two weeks later, team decides to switch to Prettier with 4-space indentation.

Old way (current): Edit 5 subagent config files manually, risk missing one, inconsistent behavior until all updated.

New way (with feature): Edit ~/.claude/agent-rules.md once, change "2-space" to "4-space". All future subagent invocations use new rule immediately.

Scenario Impact

Time saved:

• Setup: 5 minutes once vs. 5 minutes × 5 agents = 25 minutes
• Updates: 1 minute once vs. 5 minutes × 5 agents = 25 minutes per update

Error reduction:

• No risk of forgetting to update a subagent
• No inconsistencies between subagents
• No manual review needed to check style compliance

Cognitive load:

• One source of truth for rules
• Don't need to remember which agents have which rules
• Can focus on work instead of configuration management

Additional Context

Similar Features in Other Tools

Cursor IDE:

• Has .cursorrules file that applies AI coding rules globally
• All AI-generated code follows these rules automatically
• Located in project root or user home directory

GitHub Copilot:

• Can configure style preferences in IDE settings
• Suggestions follow configured style guides
• Applies consistently across all code generation

Claude Code Missing Equivalent:

• Has CLAUDE.md but it's project-level only
• No user-level equivalent for cross-project rules
• No propagation mechanism for subagents

Technical Considerations

File Loading:

• Files should be loaded at startup (similar to CLAUDE.md)
• Should support hot-reload on file changes (like IDE settings)
• Precedence should follow existing hierarchy (enterprise > local > user)

Security:

• Respect existing file permission checks
• Validate file paths to prevent directory traversal attacks
• Document that rules in these files have full agent permissions

Performance:

• Parse and cache rules at startup
• Don't re-read on every subagent invocation
• Use file watchers for change detection
• Minimal overhead (one-time parsing per session)

Backward Compatibility:

• Feature is opt-in (files don't exist by default)
• No changes to existing behavior if files not present
• Existing subagent configurations continue working unchanged

Configuration File Structure Proposal

Minimal viable implementation:

~/.claude/
  ├── settings.json              # Existing: general settings
  ├── primary-agent-rules.md     # NEW: Primary agent only rules
  ├── agent-rules.md             # NEW: All agents (shared rules)
  └── agents/                    # Existing: subagent definitions
      ├── code-reviewer.md
      └── test-writer.md

Optional enhanced implementation:

~/.claude/
  ├── settings.json
  ├── rules/                     # NEW: Rules directory
  │   ├── primary.md            # Primary agent only
  │   ├── shared.md             # All agents
  │   └── templates/            # Reusable rule templates
  │       ├── typescript.md
  │       └── python.md
  └── agents/
      └── code-reviewer.md

Settings.json Configuration Schema

{
  "$schema": "https://claude.ai/schemas/settings.json",
  "agentRules": {
    "primaryRulesFile": "~/.claude/primary-agent-rules.md",
    "sharedRulesFile": "~/.claude/agent-rules.md",
    "propagateToSubagents": true,
    "allowSubagentOverride": true,
    "loadOnStartup": true,
    "watchForChanges": true
  }
}

Documentation Gaps Discovered

During investigation, we found these related documentation gaps:

1. No documentation on whether CLAUDE.md content is available to subagents
2. No documentation on subagent context isolation details
3. No documentation on instruction inheritance patterns (because feature doesn't exist)
4. No best practices guide for managing multiple subagents
5. No examples of user-level vs project-level configuration trade-offs

These gaps made it harder to understand current behavior and discover that the feature is missing entirely.

Visual Example: Rule Propagation Flow

User creates: ~/.claude/agent-rules.md
                     ↓
          Claude Code loads at startup
                     ↓
         ┌───────────┴───────────┐
         ↓                       ↓
   Primary Agent          Subagent (code-reviewer)
   (gets shared rules)    (gets shared rules automatically)
         ↓                       ↓
   Responds to user       Generates code following rules
   with 🔵 marker         (no 🔵 marker - primary-only rule)

Related GitHub Issues / Discussions

• Unknown - unable to find existing issues about this feature
• May relate to general subagent configuration discussions
• Possibly ties into "context management" feature discussions

Implementation Priority Suggestion

Phase 1 (MVP):

• Support ~/.claude/primary-agent-rules.md (primary agent only)
• Support ~/.claude/agent-rules.md (all agents)
• Simple propagation: all subagents get shared rules automatically
• Basic settings.json configuration

Phase 2 (Enhanced):

• Per-rule scoping (primary-only, all-agents, subagents-only)
• Subagent override capabilities in frontmatter
• Rule templates and includes
• Hot-reload support

Phase 3 (Advanced):

• Rule validation and linting
• Rule conflict detection and resolution
• Enterprise policy enforcement
• Cloud-synced rules for teams

---

Meta Information:

• Discovered through user experimentation: September 29, 2025
• Affects: Users with multiple subagents (growing use case)
• Current workaround: Manual copy-paste (not scalable)
• Urgency: High for users building "subagent armies"

[baslogic]

Expanded Use Cases: User-Level Agent Rules and Rule Propagation

Executive Summary

This document expands on the original feature request by providing 20+ comprehensive use cases that demonstrate the value of user-level agent rules and rule propagation across various domains, team sizes, and workflows.

Use Cases by Category

1. Individual Developer Productivity

Use Case 1.1: Personal Coding Standards Enforcement

Scenario: Solo developer working across multiple personal projects with consistent preferences

Without feature:

• Manually specify preferences in each conversation
• Inconsistent code style across projects
• Repeated instructions for common tasks

With feature:

# ~/.claude/agent-rules.md
## Personal Coding Standards
- Always use trailing commas in multi-line arrays/objects
- Prefer template literals over string concatenation
- Use descriptive variable names (min 3 chars, max 30)
- Add TODO comments for unfinished implementations

Impact: 100% consistency across all personal projects without repeated instructions

---

Use Case 1.2: Language-Specific Rule Sets

Scenario: Polyglot developer switching between Python, JavaScript, and Go projects

Without feature:

• Context switching overhead when changing languages
• Forgetting language-specific conventions
• Subagents using wrong language idioms

With feature:

# Subagent frontmatter
---
name: python-developer
inherit_rules: true
custom_rules: ~/.claude/rules/python-specific.md
---

# ~/.claude/rules/python-specific.md
- Use snake_case for variables and functions
- Use PascalCase for classes
- Follow PEP 8 strictly
- Use type hints for all function parameters

Impact: Automatic language-appropriate conventions without manual switching

---

Use Case 1.3: Learning and Skill Development

Scenario: Junior developer learning best practices wants Claude to enforce educational patterns

With feature:

# ~/.claude/agent-rules.md
## Learning Mode
- Always explain WHY when suggesting code changes
- Include links to documentation for new concepts
- Suggest alternative approaches with trade-offs
- Add comments explaining complex logic
- Flag potential security issues with explanations

Impact: Every interaction becomes a learning opportunity across all agents

2. Team Collaboration and Standardization

Use Case 2.1: Team Onboarding Acceleration

Scenario: New team member needs to follow company coding standards immediately

Without feature:

• Long onboarding documents to read
• Inconsistent application of standards
• Senior developers spending time on code review for style issues

With feature:

# Company-provided ~/.claude/agent-rules.md
## ACME Corp Engineering Standards
- All APIs must follow REST conventions
- Use company logging library: @acme/logger
- Database queries must use parameterized statements
- All PRs require 2 approvals minimum
- Follow semantic versioning for all packages

Impact: New hires produce compliant code from day one

---

Use Case 2.2: Cross-Team Consistency

Scenario: Large organization with multiple teams working on interconnected services

With feature:

# ~/.claude/agent-rules.md
## Microservices Standards
- All services must expose /health and /metrics endpoints
- Use correlation IDs for distributed tracing
- Implement circuit breakers for external calls
- Follow OpenAPI 3.0 for API documentation
- Use standardized error response format

Impact: Seamless integration between team outputs without coordination overhead

---

Use Case 2.3: Contractor and Freelancer Management

Scenario: Company working with external contractors who need to follow internal standards

With feature:

# Provided to contractors
## Contractor Guidelines
- No direct database access - use provided APIs
- All code must include unit tests (min 80% coverage)
- Documentation required for all public methods
- Use company's Docker base images only
- Security scan must pass before commit

Impact: External contributors produce compliant code without extensive oversight

3. Security and Compliance

Use Case 3.1: Security-First Development

Scenario: Financial services company with strict security requirements

Without feature:

• Security vulnerabilities introduced accidentally
• Inconsistent application of security patterns
• Manual security review bottlenecks

With feature:

# ~/.claude/agent-rules.md
## Security Requirements
- Never log sensitive data (SSN, credit cards, passwords)
- Always use prepared statements for SQL
- Implement rate limiting on all public endpoints
- Use bcrypt for password hashing (min rounds: 12)
- All external inputs must be validated and sanitized
- Enable CSP headers on all web responses

Impact: Security best practices enforced automatically across all code generation

---

Use Case 3.2: Regulatory Compliance (GDPR/HIPAA)

Scenario: Healthcare startup needing HIPAA compliance across all development

With feature:

# ~/.claude/agent-rules.md
## HIPAA Compliance Rules
- PHI must be encrypted at rest and in transit
- Implement audit logging for all PHI access
- Use role-based access control (RBAC)
- Data retention: 6 years minimum
- Include privacy notices in all patient-facing features
- Implement automatic session timeouts (15 min)

Impact: Compliance built into development process, reducing legal risk

---

Use Case 3.3: Industry-Specific Standards

Scenario: Aerospace company following DO-178C standards for safety-critical software

With feature:

# ~/.claude/agent-rules.md
## DO-178C Compliance
- Every function must have documented requirements traceability
- All code changes require formal review documentation
- Use defensive programming (check all inputs)
- No dynamic memory allocation after initialization
- All loops must have proven termination conditions
- Document all deviations from coding standards

Impact: Safety-critical standards maintained without manual verification

4. DevOps and Infrastructure

Use Case 4.1: Infrastructure as Code Standards

Scenario: DevOps team managing Terraform/Kubernetes across multiple environments

Without feature:

• Inconsistent resource naming
• Missing required tags/labels
• Configuration drift between environments

With feature:

# ~/.claude/agent-rules.md
## IaC Standards
- Resource names: {env}-{region}-{service}-{type}
- Required tags: Environment, Owner, CostCenter, Project
- All Terraform modules must have versions pinned
- Kubernetes: Use namespaces for logical separation
- Never hardcode secrets - use secret management service
- All changes through PR - no direct applies

Impact: Infrastructure consistency across all environments

---

Use Case 4.2: CI/CD Pipeline Patterns

Scenario: Platform team ensuring consistent deployment practices

With feature:

# ~/.claude/agent-rules.md
## CI/CD Requirements
- All builds must run security scanning (Snyk/Sonar)
- Deploy to staging before production
- Implement blue-green deployments for zero downtime
- Include rollback procedures in all deployments
- Performance tests required for API changes
- Notify #deployments Slack channel for production changes

Impact: Reliable, consistent deployments across all services

---

Use Case 4.3: Monitoring and Observability

Scenario: SRE team ensuring all services are properly instrumented

With feature:

# ~/.claude/agent-rules.md
## Observability Standards
- Implement OpenTelemetry for all services
- Log levels: DEBUG (dev), INFO (staging), WARN (prod)
- Create dashboards for: latency, errors, traffic, saturation
- Alert thresholds: p99 latency > 1s, error rate > 1%
- Include runbooks for all critical alerts
- Use structured logging (JSON format)

Impact: Comprehensive observability from initial development

5. Documentation and Communication

Use Case 5.1: Documentation Standards

Scenario: Technical writer managing documentation across multiple products

Without feature:

• Inconsistent documentation format
• Missing critical sections
• Varying levels of detail

With feature:

# ~/.claude/agent-rules.md
## Documentation Standards
- All docs must include: Overview, Prerequisites, Steps, Troubleshooting
- Use active voice and present tense
- Include code examples for all API endpoints
- Add diagrams for complex architectures (mermaid format)
- Version all documentation with product releases
- Include "Last Updated" timestamp

Impact: Professional, consistent documentation across all products

---

Use Case 5.2: API Documentation Generation

Scenario: API team maintaining OpenAPI specifications

With feature:

# ~/.claude/agent-rules.md
## API Documentation Rules
- Every endpoint must have: summary, description, examples
- Include possible error responses with explanations
- Document rate limits and authentication requirements
- Use consistent schema references ($ref)
- Include pagination details for list endpoints
- Version APIs using URL path (/v1/, /v2/)

Impact: Complete, consistent API documentation automatically

---

Use Case 5.3: Customer Communication Templates

Scenario: Support engineering team responding to customer issues

With feature:

# ~/.claude/agent-rules.md
## Customer Communication
- Always acknowledge the issue first
- Provide estimated resolution time
- Include workaround if available
- Use empathetic language
- Follow up within 24 hours
- Include ticket number in all communications

Impact: Professional, consistent customer experience

6. Testing and Quality Assurance

Use Case 6.1: Test-Driven Development Enforcement

Scenario: Team practicing TDD wants to ensure tests are always written first

Without feature:

• Developers forget to write tests first
• Inconsistent test coverage
• Varying test quality

With feature:

# ~/.claude/agent-rules.md
## TDD Requirements
- Write failing test before implementation
- One assertion per test method
- Test names: should_ExpectedBehavior_When_Condition
- Include edge cases and error scenarios
- Mock external dependencies
- Aim for 90% code coverage minimum

Impact: TDD practiced consistently across all development

---

Use Case 6.2: E2E Testing Patterns

Scenario: QA team ensuring comprehensive end-to-end test coverage

With feature:

# ~/.claude/agent-rules.md
## E2E Testing Standards
- Test critical user journeys first
- Use page object pattern for maintainability
- Include visual regression tests for UI changes
- Test across: Chrome, Firefox, Safari, Edge
- Mobile responsive: test at 320px, 768px, 1920px
- Data cleanup after each test run

Impact: Comprehensive, maintainable test suites

---

Use Case 6.3: Performance Testing Requirements

Scenario: Performance engineer ensuring all services meet SLAs

With feature:

# ~/.claude/agent-rules.md
## Performance Standards
- Load test at 2x expected peak traffic
- Response time SLA: p50 < 200ms, p99 < 1s
- Include memory leak detection in tests
- Test graceful degradation under load
- Document performance baseline for each release
- Alert on 10% performance regression

Impact: Performance requirements met before production

7. AI Agent Orchestration

Use Case 7.1: Multi-Agent Workflow Coordination

Scenario: Complex tasks requiring multiple specialized agents working in sequence

Without feature:

• Manual coordination between agents
• Inconsistent handoffs between agents
• Lost context during transitions

With feature:

# ~/.claude/agent-rules.md
## Agent Orchestration Rules
- Always summarize findings before passing to next agent
- Use standardized data formats for agent communication
- Include confidence scores in recommendations
- Document assumptions made during analysis
- Preserve original user intent through workflow
- Report back to primary agent upon completion

Impact: Smooth multi-agent workflows without manual intervention

---

Use Case 7.2: Agent Specialization Management

Scenario: Building specialized agents for different domains (legal, medical, financial)

With feature:

# Legal agent frontmatter
---
name: legal-advisor
inherit_rules: false  # Don't inherit general rules
custom_rules: ~/.claude/rules/legal-specific.md
---

# ~/.claude/rules/legal-specific.md
- Always include disclaimer about not being legal advice
- Cite relevant statutes and case law
- Consider jurisdiction-specific variations
- Flag potential conflicts of interest
- Maintain attorney-client privilege concepts

Impact: Domain-appropriate behavior without compromising specialization

---

Use Case 7.3: Agent Performance Optimization

Scenario: Optimizing agent performance by routing to appropriate specialists

With feature:

# ~/.claude/primary-agent-rules.md
## Agent Routing Logic
- Use code-optimizer for performance issues
- Use security-scanner for vulnerability checks
- Use documentation-writer for README updates
- Use test-generator for test creation
- Batch similar tasks to same agent
- Prefer specialized agents over general-purpose

Impact: Optimal agent utilization and faster task completion

8. Education and Training

Use Case 8.1: Computer Science Education

Scenario: Professor using Claude Code to help students learn proper programming

With feature:

# ~/.claude/agent-rules.md
## Educational Mode
- Explain algorithms step-by-step
- Show time/space complexity for all solutions
- Provide multiple solution approaches
- Include visualization suggestions for complex concepts
- Reference classic CS papers when relevant
- Suggest practice problems for reinforcement

Impact: Consistent educational approach across all interactions

---

Use Case 8.2: Bootcamp Instructor Support

Scenario: Coding bootcamp providing consistent guidance to students

With feature:

# ~/.claude/agent-rules.md
## Bootcamp Guidelines
- Use only concepts covered in current week's curriculum
- Provide hints rather than complete solutions
- Encourage debugging skills - don't fix immediately
- Reference course materials and lectures
- Suggest pair programming for difficult concepts
- Include industry context for practical relevance

Impact: Aligned learning experience with curriculum goals

---

Use Case 8.3: Corporate Training Programs

Scenario: Enterprise rolling out new technology training

With feature:

# ~/.claude/agent-rules.md
## Migration Training Rules
- Show before/after code examples
- Highlight breaking changes prominently
- Provide migration scripts where applicable
- Include rollback procedures
- Document common pitfalls
- Reference internal wiki for detailed guides

Impact: Smooth technology adoption across organization

9. Open Source Contribution

Use Case 9.1: Open Source Project Standards

Scenario: Maintainer ensuring consistent contribution quality

Without feature:

• Time spent on style reviews
• Inconsistent PR quality
• Contributor frustration with rejections

With feature:

# ~/.claude/agent-rules.md
## OSS Contribution Rules
- Follow project's CONTRIBUTING.md strictly
- Include tests for all new features
- Update CHANGELOG.md with changes
- Sign commits with GPG key
- Reference issue number in PR description
- Keep PRs focused - one feature per PR

Impact: Higher quality contributions, faster PR reviews

---

Use Case 9.2: License Compliance

Scenario: Ensuring open source license compliance in contributions

With feature:

# ~/.claude/agent-rules.md
## License Compliance
- Check dependency licenses for compatibility
- Include license headers in new files
- Attribute code from other sources properly
- Don't mix incompatible licenses (GPL/MIT)
- Document all third-party dependencies
- Use SPDX license identifiers

Impact: Legal compliance maintained automatically

10. Research and Development

Use Case 10.1: Research Code Standards

Scenario: Research team ensuring reproducible results

Without feature:

• Difficulty reproducing experiments
• Inconsistent data handling
• Missing documentation of parameters

With feature:

# ~/.claude/agent-rules.md
## Research Standards
- Set random seeds for reproducibility
- Document all hyperparameters in config files
- Include environment setup in README
- Version control data with DVC
- Use meaningful experiment names with timestamps
- Archive results with code version

Impact: Reproducible research across team members

---

Use Case 10.2: Prototype Development

Scenario: Innovation team rapidly prototyping new ideas

With feature:

# ~/.claude/agent-rules.md
## Rapid Prototyping Rules
- Prioritize functionality over optimization
- Add TODO comments for production considerations
- Use mock data for quick iterations
- Document assumptions and limitations
- Include "NOT FOR PRODUCTION" warnings
- Create simple UI for demos

Impact: Faster prototype development with clear boundaries

11. Specialized Domain Applications

Use Case 11.1: Game Development Standards

Scenario: Game studio maintaining consistent code across multiple titles

With feature:

# ~/.claude/agent-rules.md
## Game Dev Standards
- Use object pooling for frequently spawned objects
- Implement LOD (Level of Detail) for performance
- Follow Unity/Unreal naming conventions
- Cache component references in Start/Awake
- Use events/delegates for decoupled communication
- Profile performance on target hardware

Impact: Optimized, maintainable game code

---

Use Case 11.2: Data Science Workflows

Scenario: Data science team ensuring consistent analysis approaches

With feature:

# ~/.claude/agent-rules.md
## Data Science Standards
- Always perform EDA before modeling
- Check for data leakage in feature engineering
- Use stratified splits for imbalanced datasets
- Document feature importance and selection
- Include cross-validation scores
- Version control models with MLflow

Impact: Rigorous, reproducible data science practices

---

Use Case 11.3: Embedded Systems Development

Scenario: IoT company developing firmware for resource-constrained devices

With feature:

# ~/.claude/agent-rules.md
## Embedded Standards
- Minimize dynamic memory allocation
- Use fixed-point arithmetic when possible
- Implement watchdog timers
- Check return values for all system calls
- Use power-saving modes when idle
- Document memory and power consumption

Impact: Efficient, reliable embedded code

12. Workflow Automation

Use Case 12.1: Code Review Automation

Scenario: Automating code review feedback with consistent standards

With feature:

# ~/.claude/agent-rules.md
## Code Review Checklist
- Check for proper error handling
- Verify logging at appropriate levels
- Ensure backward compatibility
- Look for potential race conditions
- Validate input sanitization
- Confirm documentation updates

Impact: Consistent, thorough code reviews

---

Use Case 12.2: Migration and Refactoring

Scenario: Large-scale codebase modernization project

With feature:

# ~/.claude/agent-rules.md
## Migration Rules
- Maintain backward compatibility during transition
- Create feature flags for gradual rollout
- Write migration scripts for data changes
- Update all related documentation
- Include deprecation notices with timelines
- Test both old and new code paths

Impact: Smooth, risk-managed migrations

---

Use Case 12.3: Release Management

Scenario: Coordinating releases across multiple services

With feature:

# ~/.claude/agent-rules.md
## Release Standards
- Follow semantic versioning strictly
- Generate changelog from commit messages
- Tag releases in git
- Update version in package files
- Create GitHub release with artifacts
- Notify stakeholders via Slack/email

Impact: Predictable, well-documented releases

Implementation Benefits Summary

Quantitative Benefits

1. Time Savings

   • Setup time: 90% reduction (5 min vs 50 min for 10 agents)
   • Update time: 95% reduction (1 min vs 20 min for changes)
   • Review time: 60% reduction (automated style compliance)

2. Error Reduction

   • Configuration errors: 100% elimination (single source of truth)
   • Style inconsistencies: 100% elimination (automatic application)
   • Security vulnerabilities: 80% reduction (enforced patterns)

3. Productivity Gains

   • Onboarding time: 50% reduction (immediate compliance)
   • Context switching: 70% reduction (automatic rule loading)
   • Cognitive load: 60% reduction (no manual rule tracking)

Qualitative Benefits

1. Developer Experience

   • Reduced frustration from repetitive instructions
   • Focus on creative problem-solving vs configuration
   • Confidence in consistent outputs

2. Team Collaboration

   • Shared understanding of standards
   • Reduced friction in code reviews
   • Better integration between team outputs

3. Business Value

   • Faster time to market
   • Reduced technical debt
   • Lower maintenance costs
   • Improved security posture
   • Better regulatory compliance

Conclusion

The user-level agent rules and rule propagation feature would transform Claude Code from a powerful tool into an intelligent, context-aware development partner that automatically enforces standards, maintains consistency, and scales effortlessly across teams and projects. The use cases presented here demonstrate clear, measurable value across diverse domains and team structures, making this feature essential for serious Claude Code adoption in professional environments.

The impact extends beyond individual productivity to enable entirely new workflows and collaboration patterns that are currently impossible or impractical without centralized rule management and propagation capabilities.

[coygeek]

This is an incredibly well-thought-out and detailed feature request. The use cases you've outlined are fantastic and really highlight the need for a robust, hierarchical way to manage agent instructions.

As a fellow user who has spent some time digging through the documentation, it looks like the Claude Code team has already implemented a system that covers a lot of these scenarios, though perhaps with slightly different naming. I wanted to share what I found in case it helps you (and others) achieve what you're looking for with the current feature set.

Based on the en/docs/claude-code/memory document, there's a multi-layered "memory" system using CLAUDE.md files that seems to map directly to your idea of user-level rules and propagation.

1. User-Level Agent Rules

You proposed a central ~/.claude/agent-rules.md. The documentation describes an equivalent feature called User Memory, which is located at ~/.claude/CLAUDE.md.

From the docs:

User memory (~/.claude/CLAUDE.md): Personal preferences for all projects.

This seems to be the exact mechanism for your use cases like "Personal Coding Standards Enforcement" (1.1) and others where you want a personal, global set of instructions that apply everywhere.

2. Rule Propagation and Hierarchy

You mentioned the need for rules to propagate down to sub-agents. The documentation describes a clear hierarchy for how these CLAUDE.md files are loaded:

1. Enterprise Policy (/etc/claude-code/CLAUDE.md)
2. Project Memory (./CLAUDE.md)
3. User Memory (~/.claude/CLAUDE.md)

The docs state: "All memory files are automatically loaded into Claude Code's context when launched." This suggests that the context for the main agent, and by extension its sub-agents, is built from this hierarchy. This seems to cover the automatic inheritance you're looking for.

3. Language-Specific and Custom Rule Sets for Sub-agents

This is the most interesting part. You proposed frontmatter like inherit_rules: true and custom_rules: ~/.claude/rules/python-specific.md.

While the docs don't mention that specific frontmatter, they do describe a feature called CLAUDE.md imports that looks like it can achieve the same result. You can use @ to import other files directly into a CLAUDE.md file or an agent's prompt.

So, to achieve your "Language-Specific Rule Sets" (Use Case 1.2), you could create your specialized agent file like this:

File: ~/.claude/agents/python-developer.md

---
name: python-developer
description: A specialist for Python development tasks.
tools: Read, Write, Bash
---

You are an expert Python developer. When working on Python code, you MUST adhere to the following standards and best practices.

# Core Python Standards
@~/.claude/rules/python-specific.md

# General Company Standards
@~/dev/company-project/.claude/CLAUDE.md

And your rule file would be:

File: ~/.claude/rules/python-specific.md

- Use snake_case for variables and functions.
- Follow PEP 8 strictly.
- Use type hints for all function parameters.

This @ import mechanism seems to provide the granular control you're looking for, allowing you to compose rule sets for different agents. For your "Agent Specialization Management" (Use Case 7.2), you would just omit the @ import for the general rules to prevent inheritance.

It seems like the core functionality you're requesting is largely in place through the combination of hierarchical CLAUDE.md memory files and the @ import feature. Maybe the underlying feature request here is to make this relationship more explicit and discoverable, perhaps through frontmatter as you suggested, rather than requiring users to know about the import syntax within the prompt itself.

What do you think? Does this existing system cover your use cases, or is there a gap I'm missing? Either way, your detailed breakdown is an amazing resource for anyone looking to use Claude Code more effectively. Great work

[baslogic]

@coygeek

You're absolutely right that the CLAUDE.md memory system covers many of the use cases I outlined. I really appreciate you taking the time to map my proposal to the current features.

You've highlighted some great points:

• The ~/.claude/CLAUDE.md does indeed serve as user-level rules
• The hierarchy (Enterprise → Project → User) provides inheritance
• The @ import mechanism allows for modular rule composition

However, I think there are still some gaps between the current implementation and what I'm proposing:

1. Explicit subagent propagation control: While CLAUDE.md files are loaded into context, it's unclear if/how they propagate to subagents spawned by the Task tool. In my testing, subagents don't consistently follow rules from the parent's CLAUDE.md context. The
proposed inherit_rules frontmatter would make this explicit and controllable.

2. Subagent-specific rule scoping: The current system loads all memory files globally. My proposal would allow certain rules to apply ONLY to specific subagents (e.g., strict linting rules for code-reviewer but not for prototype-builder).

3. Dynamic rule selection: The @ import is great for static composition, but the proposed system would allow the primary agent to dynamically select which rules to pass to each subagent based on the task context.

4. Rule precedence and conflicts: When multiple CLAUDE.md files exist, it's not clear how conflicts are resolved. The proposed configuration would make precedence explicit.

You're right that much of the infrastructure exists - perhaps the real ask here is:

1. Better documentation on how memory propagates to subagents
2. More explicit control mechanisms (like the frontmatter approach)
3. Validation that subagents actually receive and apply the inherited context

Would love to hear if you've found ways to ensure subagents consistently follow your CLAUDE.md rules, or if you've experienced the same inconsistency I have?

[github-actions]

This issue has been inactive for 30 days. If the issue is still occurring, please comment to let us know. Otherwise, this issue will be automatically closed in 30 days for housekeeping purposes.

[github-actions]

This issue has been automatically closed due to 60 days of inactivity. If you're still experiencing this issue, please open a new issue with updated information.

[github-actions]

This issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.