[RFC]: Claude Code Native Implementation -- Multi-Agent Skills Architecture

[anhyobin]

[RFC]: Claude Code Native Implementation -- Multi-Agent Skills Architecture

Summary

Propose adding a Claude Code-native implementation of AIDLC that leverages Claude Code's unique capabilities (agents, skills, hooks, rules) to deliver the same AIDLC methodology with improved workflow enforcement, context efficiency, and developer experience. This is a platform-specific optimization, not a replacement for the existing rule-file approach.

Motivation

The current Claude Code setup copies core-workflow.md to CLAUDE.md (~538 lines always loaded). This works but doesn't leverage Claude Code's native features:

1. Context cost: 538 lines permanently in context vs ~73 lines with on-demand skill loading (86% reduction)
2. Role enforcement: The rule file says "don't modify code during review" as text. Native agents enforce disallowedTools: [Write, Edit] at the system level -- the reviewer literally cannot write files.
3. Workflow automation: Session resumption requires the AI to "remember to read state". Native hooks auto-detect project state and guide the user on every session start.
4. Extensions: Opt-in files are always loaded. Native implementation uses paths-based conditional loading -- disabled extensions consume zero context.

Benchmark results (tested on Serverless Order Management API scenario across all 14 AIDLC stages):

Approach	Pass Rate	Details
Claude Code Native	76/76 (100%)	14 skills, 4 agents, 6 rules, 2 hooks
Upstream Rule File	73/76 (96.1%)	core-workflow.md as CLAUDE.md
No Guidance	54/71 (76.1%)	No AIDLC rules at all

The native implementation achieves 100% compliance with AIDLC methodology patterns, particularly excelling in areas requiring strict structural enforcement (e.g., quality gate's 2-phase pipeline, functional design's technology-agnostic constraint).

Detailed Proposal

Architecture

.claude/
├── CLAUDE.md                              # Lightweight routing (~73 lines)
├── settings.json                          # Hooks + permissions
├── agents/                                # 4 role-based agents
│   ├── aidlc-analyst.md                   #   Bash disabled, design-only
│   ├── aidlc-architect.md                 #   AWS CLI + MCP access
│   ├── aidlc-developer.md                 #   Full tool access, maxTurns: 100
│   └── aidlc-reviewer.md                  #   Write/Edit disabled (read-only)
├── rules/                                 # Cross-cutting rules (auto-loaded)
│   ├── aidlc-content-validation.md
│   ├── aidlc-error-handling.md
│   ├── aidlc-terminology.md
│   ├── aidlc-workflow-changes.md
│   ├── aidlc-ext-security-baseline.md     #   Conditional (paths-based)
│   └── aidlc-ext-property-based-testing.md
└── skills/                                # 14 slash commands
    └── aidlc-{stage}/SKILL.md             #   /aidlc-detect through /aidlc-status

Key Design Decisions

1. Skills as Slash Commands
Each AIDLC stage is a separate skill (/aidlc-detect, /aidlc-requirements, etc.). Skills run in context: fork with assigned agents, providing context isolation between stages.

2. Agent-Based Role Separation

• aidlc-analyst (9 skills): Analysis and design. Cannot run Bash or Edit existing files.
• aidlc-architect (1 skill): Infrastructure design. Has Bash for AWS CLI and MCP tool access.
• aidlc-developer (1 skill): Code generation. Full tool access.
• aidlc-reviewer (2 skills): Verification. Cannot Write or Edit -- system-level enforcement.

3. Rules for Cross-Cutting Concerns
Content validation, error handling, terminology, and workflow changes are in .claude/rules/ -- auto-loaded by all agents and the main session.

4. Extensions via Conditional Rules
Security baseline and property-based testing extensions use paths frontmatter. When the team opts in during requirements analysis, a marker file is created that activates the rule.

5. Hooks for Automation

• SessionStart: Auto-detects AIDLC project state, shows welcome message for new projects
• SubagentStop: Auto-logs to audit.md when any AIDLC agent completes

Upstream Compatibility

• Same three-phase lifecycle (Inception → Construction → Operations)
• Same stage sequence and gate rules
• Same question file format ([Answer]: tags, A/B/C/X options)
• Same artifact structure (aidlc-docs/)
• Extensions aligned with upstream's security-baseline and property-based-testing
• Content derived from upstream common/ rules (content-validation, error-handling, terminology, workflow-changes)

What's Different

Aspect	Upstream Rule File	Claude Code Native
Context cost	~538 lines always loaded	~73-line CLAUDE.md + skills on demand
Role enforcement	Text instructions	disallowedTools system enforcement
Stage execution	AI interprets rules	Dedicated skill per stage with fork context
Session resumption	AI must remember to read state	SessionStart hook auto-detects
Audit logging	AI must remember to log	SubagentStop hook auto-records
Extensions	Always loaded opt-in files	paths-based conditional loading

Alternatives Considered

1. Single Agent Skill (PR #135 approach)
Package core-workflow.md as one SKILL.md with references/. Simpler but doesn't leverage multi-agent role separation, tool isolation, hooks, or conditional rules.

2. Keep rule file only
Continue with CLAUDE.md approach. Works but misses Claude Code-specific optimizations.

3. Hybrid approach
Use upstream rule files as .claude/rules/ references while adding skills for UX. Rejected because it creates duplicate sources of truth.

Drawbacks

• Claude Code only: This implementation doesn't work on other platforms (Cursor, Kiro, Q Developer). It's additive, not a replacement.
• Maintenance: Changes to upstream stage logic need to be reflected in both the rule files and the skill files. However, the skill structure mirrors the stage structure 1:1, so changes map directly.
• Complexity: 14 skill files + 4 agent files + 6 rule files vs 1 rule file. The tradeoff is more files for better enforcement and developer experience.

Additional Context

Test Methodology

All 14 AIDLC stages were tested using a Serverless Order Management API scenario (Cognito + Lambda + DynamoDB + SQS + EventBridge + Stripe, 4 units, TypeScript/CDK). Each stage was evaluated with:

• Native: Read the skill SKILL.md and follow its instructions
• Upstream: Read core-workflow.md (538 lines) and follow the relevant stage rules
• Baseline: No AIDLC guidance at all

42 total agent evaluations were run. Results graded against 76 assertions covering: structural compliance (question format, [Answer]: tags, X) Other options), methodology adherence (4-dimension analysis, INVEST criteria, EXECUTE/SKIP decisions, 2-phase gate pipeline), and artifact completeness. The implementation is language-agnostic -- all skills, agents, and rules adapt to the user's language automatically.

Implementation

• PR: feat: add Claude Code native implementation with multi-agent architecture #145
• Source: https://github.com/anhyobin/aidlc-workflows/tree/feat/claude-code-native-implementation/platforms/claude-code

Related PRs

• docs: add Agent Skill setup option for Claude Code #135 -- single-skill packaging approach. This proposal extends beyond that with multi-agent architecture, system-level tool isolation, automated hooks, and conditional extension rules.