SOP Standards

Development Workflow

ATLC Workflow

A3C Claude Code SOP

Mirion Medical Claude Code Standard Operating Procedure — Version 1.0

Document Control

Document Title	A3C Claude Code Usage for Requirements, Development, and QA
Document Type	Standard Operating Procedure (SOP)
Business Area	Mirion Medical
Owner	AI Adoption and Acceleration Committee (A3C)
Version	1.0 (03/28/2026 Dave Olund)
Status	Published

1. Purpose
2. Scope
3. Definitions
4. Roles and Responsibilities
5. Core Operating Standards
6. Required Shared Artifacts
7. TPM Workflow — Requirements and Problem Definition
8. Developer Workflow — Analysis, Planning, Implementation, and Documentation
9. QA Workflow — Manual and Automated Test Authoring
10. Prompting and Session Standards
11. Pull Request Review and Quality Gate Standards
12. Accountability Standards
13. Branching, Persistence, and Handoff Rules
14. Connector, Plugin, and Integration Guardrails
15. Controlled Rollout and Mentorship
16. Records and Retention
A. Claude Commands and Prompt Patterns Quick Reference
B. Background Notes (Non-Procedural)
C. Recommended Minimum Contents for CLAUDE.md

1. Purpose

This SOP defines how Claude Code is to be used to support requirements authoring, software development, documentation, and QA test creation in a controlled, reviewable, and maintainable way. It establishes standard practices for TPMs, developers, and QA staff so that AI-assisted work improves delivery without reducing engineering rigor, traceability, or accountability.

2. Scope

This SOP applies to approved Claude Code usage for product requirements, design exploration, code generation, documentation updates, review preparation, manual test case generation, and automation test scaffolding within approved organizational environments. It covers collaborative use across TPM, development, and QA roles where work is performed in shared repositories and supported by common Claude context files and project plans.

Approved Platform: Microsoft Foundry / Azure AI Foundry

3. Definitions

Claude Code: The approved agentic coding environment used to assist with analysis, planning, implementation, and documentation tasks.
CLAUDE.md: The concise master context file for a repository, used as the primary index for project guidance and references. Described as the “central brain” that Claude references as it starts making choices.
.claude/docs/: Supporting markdown documentation containing deeper architectural, functional, testing, or process context.
Project Plan: A phased markdown plan used to guide implementation of a feature, migration, bug fix, or test effort.
lessons.md: A shared markdown file capturing recurring issues, anti-patterns, troubleshooting notes, and team learnings.
AI-assisted work: Any requirement, code, test case, document, or analysis that is created or materially modified with Claude Code support.

4. Roles and Responsibilities

4.1 TPM Responsibilities

Use Claude Code to improve the clarity, completeness, and implementation-readiness of requirements before development begins.
Ensure requirements, assumptions, acceptance criteria, and open questions are captured in reusable markdown artifacts when needed for downstream work.
Resolve critical ambiguity before handoff instead of allowing the tool to make unreviewed product assumptions.
Utilize Claude to identify and create drafts of: risks for the overall risk matrix, any regulatory compliance or submission needs, drafts of critical requirements, drafts of user acceptance test criteria.

4.2 Developer Responsibilities

Use Claude Code to analyze the codebase, create implementation plans, implement changes in phases, and update shared technical documentation as needed.
Review AI-generated code before opening a pull request and ensure appropriate verification has been completed. Verification means that the developer understands all the code that is generated and runs the code to ensure quality and compatibility.
Maintain branch discipline, commit frequently, and persist shared Claude artifacts when they are needed for handoff or future work.

4.3 QA Responsibilities

Use Claude Code to create and refine manual and automated test assets from reviewed requirements and implementation context.
Review generated test assets for relevance, realism, completeness, and maintainability before adoption.
Capture repeatable QA prompting patterns and lessons learned in shared markdown artifacts when they may benefit future work.

4.4 Reviewers / Technical Leads / Architects

Review AI-assisted changes for correctness, maintainability, and alignment with product architecture and intended behavior.
Provide escalated review for larger, structural, or higher-risk changes when standard peer review is not sufficient.

4.5 A3C / Governance Responsibilities

Maintain and evolve adoption guardrails, best practices, and enablement guidance for Claude Code usage.
Coordinate controlled rollout, mentorship, and decisions related to plugins, connectors, and shared standards.

5. Core Operating Standards

Requirements and/or plan quality must be treated as a prerequisite for effective AI-assisted development and testing.
AI-generated output must receive the same or greater scrutiny as manually authored work.
The person who submits or commits AI-assisted work remains accountable for the result.
Work must be grounded in shared context and version control.
Claude session context must be managed deliberately to preserve output quality.
Connectors and broader rollout controls must be introduced only under defined guardrails.

6. Required Shared Artifacts

6.1 CLAUDE.md

Each active repository should maintain a concise CLAUDE.md file that serves as the master index of project context. It should contain only the information that Claude needs regularly, such as project overview, tech stack, key directories, build/test commands, and references to deeper documentation.

6.2 Supporting Documentation in .claude/docs/

Detailed documentation should be stored in smaller topic-specific markdown files under .claude/docs/. Examples include architecture notes, patterns, standards, domain rules, dependencies, testing guidance, and edge-case references. Technical docs will also include domain-specific context files like patient_context.md and domain_glossary.md for domain terminology.

6.3 Project Plans

Features, migrations, larger bug fixes, and major QA efforts should use phased project plans stored in a defined markdown location such as .claude/project/plans/ or an equivalent as work progresses.

6.4 lessons.md

A lessons.md file should be maintained to capture repeat issues, debugging lessons, anti-patterns, clarifications, and team learnings that should influence future Claude-assisted work across sessions.

6.5 Persisted Handoff Artifacts

When AI-assisted work moves from one role to another, the minimum persisted artifacts should include any shared CLAUDE.md updates, relevant .claude/docs updates, active project plans, and lessons learned that materially affect handoff and continuity.

7. TPM Workflow — Requirements and Problem Definition

Review or update the shared project context before generating or refining requirements.
Use Claude Code to analyze existing requirements, stories, notes, and reference materials before drafting new or revised requirements.
Refine outputs into implementation-ready requirement statements, acceptance criteria, assumptions, and open questions.
Persist any requirement artifacts that are intended to guide development or QA in reusable markdown form.
Resolve critical ambiguity before handoff rather than relying on unreviewed assumptions.

Required TPM outputs: Refined requirements artifact, acceptance criteria, assumptions, impacted areas, and any open questions or handoff notes needed by development and QA.

8. Developer Workflow — Analysis, Planning, Implementation, and Documentation

Perform all Claude-assisted development work in a version-controlled branch.
Review shared context files and create or refine a phased implementation plan before generating code.
For non-trivial changes, an implementation plan must be reviewed and accepted by the developer (and lead where applicable) before code generation begins.
Implement work in small, verifiable increments rather than large uncontrolled batches.
Use available verification methods such as tests, builds, expected outputs, screenshots, or logs when applicable.
Update shared documentation when material technical assumptions, patterns, or behaviors change.
Commit frequently enough to support rollback if the work begins to diverge from intended design or quality expectations.
Carefully review generated output and simplify before opening a pull request.
AI-assisted changes must pass all applicable verification steps (builds, tests, lint, traceability) before PR submission. Verification failures may not be deferred to reviewers.

Developer deliverables: Reviewed plan, code changes in branch, updated shared context when needed, and verification evidence appropriate to the change.

9. QA Workflow — Manual and Automated Test Authoring

Start from reviewed requirements and relevant implementation context.
Use Claude Code to generate first-pass manual test cases, automation candidates, test data ideas, or draft automation assets.
Refine generated outputs to reduce excess steps, remove low-value detail, and improve realism and maintainability.
Capture successful QA prompting patterns and lessons learned in shared documentation when they benefit future work.
Review generated test assets with the same discipline applied to any other QA artifact before adoption.

QA deliverables: Reviewed manual test cases, automation candidates, draft scripts, coverage notes, and lessons learned updates. Differentiating two different Claude files (Automation and Manual) separately with different context files.

10. Prompting and Session Standards

10.1 Prompting Standards

Prompts should state the objective, desired output, relevant files or documents to review first, and any verification expectations.
Complex tasks should be broken into stages such as analyze, plan, implement, verify, simplify, and review.
When assumptions matter, prompts should encourage Claude to surface clarifying questions and those answers should be preserved when they materially affect implementation.
Shared prompts or prompt templates that materially improve team outcomes should be documented for reuse.
.claude/commands will also contain custom slash commands for the team to use for quick template prompt use.

10.2 Session Standards

Use clearly named sessions where practical so work can be resumed intentionally.
Monitor session context growth and compact or restart sessions when quality begins to degrade.
When restarting a session, re-ground Claude from persisted plans and shared documentation rather than relying on memory alone.

11. Pull Request Review and Quality Gate Standards

11.1 General Rule

Any pull request containing AI-generated or AI-assisted changes must be reviewed with the same or greater rigor as a manually authored pull request.

11.2 Author Responsibilities Before Opening a PR

Review the generated code or documentation for correctness and quality.
Confirm that the implementation aligns with intended architecture and requirement direction.
Ensure shared documentation has been updated where material assumptions or structures changed.
Complete verification steps appropriate to the change before requesting review.

11.3 Reviewer Responsibilities

Review correctness, maintainability, and architectural fit.
Review relevant supporting markdown artifacts when they contain assumptions, plan steps, or clarifying decisions that influenced the implementation.
AI-assisted self-review may be used to augment human review, provided it does not replace peer or lead approval.
Confirm alignment with product intent and shared standards, not only basic build or test success.

11.4 Escalated Review

Larger, structural, risky, or architecture-significant changes should receive review from senior technical leads or architects in addition to standard peer review.

11.5 Unit Tests and Maintainability

New features or materially changed behaviors should include unit tests or other suitable verification coverage so the code remains maintainable and reviewable over time.

12. Accountability Standards

The individual who submits or commits AI-assisted work remains accountable for the quality, correctness, and maintainability of that work. AI assistance does not reduce ownership, review expectations, or defect accountability. All AI-assisted changes must maintain requirement traceability from ticket to commits and pull request.

13. Branching, Persistence, and Handoff Rules

All Claude-assisted implementation work must occur in a branch rather than directly in the main line.
Shared repository context such as CLAUDE.md and relevant .claude/docs files must be committed when they materially affect future work.
Project plans used to drive a feature, migration, or QA effort should be persisted when they are part of the active workflow or needed for handoff.
lessons.md updates should be committed when they affect future prompting, coding, debugging, or QA behavior.
Handoffs between TPM, development, and QA should include enough persisted context for the next contributor to understand the current state and intended direction of the work.

14. Connector, Plugin, and Integration Guardrails

New connectors, plugins, or external integrations must not be added to the standard workflow until governance and usage guardrails are defined.
The team must determine what integrations are permitted, who may use them, and what reviews or controls are required before broader enablement.
Integrations that write back to systems of record should be introduced only after quality checks and approval steps are established.

15. Controlled Rollout and Mentorship

Early adoption should be led by experienced TPM, QA, and development leaders while standards are being established.
Junior staff may experiment, but should not be expected to independently drive production-impacting Claude-assisted implementation until team guidelines are established.
A mentorship model should be used so experienced users can guide others on setup, shared context usage, prompting patterns, and common failure modes.
Software Development will follow the controlled rollout documented in TQMS_ADLC_ProcessFlow.xlsx.

16. Records and Retention

Repositories and project workspaces should retain committed Claude-related artifacts in accordance with normal engineering repository practices and any applicable organizational retention standards. Teams should avoid committing low-value or redundant generated files, but should preserve the markdown artifacts needed for continuity, auditability, and reuse.

Appendix A — Claude Commands and Prompt Patterns Quick Reference

This appendix captures commands, workflows, and prompt patterns. It is intended as a practical reference, not as a replacement for the main SOP instructions.

A1. Recommended Claude Commands

Custom slash commands will be stored in .claude/commands and will be added to the below list in the future.

/plan — Start a new feature or create a structured implementation plan
/clear — Clean up current prompt/context when needed
/debug — Iterate on errors, logs, or failing builds
/cost — Check token cost and compare effort against time saved
/rename — Name a session for easier resumption later
/resume — Jump back into a named session
/memory — Update dynamic remembered rules between sessions
/context — Check how much context window is being consumed
/compact — Use before context saturation becomes too high
/status — Confirm API usage, environment/resources, and default model

A2. New Project / Repository Setup Prompt Pattern

Analyze this codebase and create a CLAUDE.md file following these principles:
1. Keep it under 150 lines total - focus only on universally applicable information
2. Cover the essentials: WHAT (tech stack, project structure), WHY (purpose), and HOW (build/test commands)
3. Use Progressive Disclosure: instead of including all instructions, create a brief index pointing to other markdown files in .claude/docs/ for specialized topics
4. Include file:line references instead of code snippets
5. Assume I’ll use linters for code style - don’t include formatting guidelines

Structure it as: project overview, tech stack, key directories/their purposes, essential build/test commands, and a list of additional documentation files Claude should check when relevant.

A3. Planning Prompt Pattern

Create a new folder under the .claude/docs repo named [project name]. Reference all existing documentation to fully analyze and understand where [key element] exists today. Create a plan to [objective]. The plan should include a full analysis of the codebase, areas where [specific areas of focus]. Include details on how this plan will be implemented and critical tests to ensure no functionality is broken. The plan should be broken out in phases of modular work that can be verified through testing.

A4. “Pick Up Where We Left Off” Prompt Pattern

Review the project-plan folder and pick up on the current phase of the project.
Ensure that documents for reference architecture and patterns are reviewed as needed in the .claude/docs folder.
Ask clarifying questions prior to executing the next phase.

A5. Debugging Prompt Pattern

/debug build this project, making sure to understand the project file located in the .claude/docs/project_plans folder. Debug any issues that arise, noting any code changes that need to be made for a successful build.

A6. Documentation Prompt Example

Fully review and document the Test folder code, add any necessary documentation to the .claude/docs folder, and add any necessary references to the claude.md file in the additional documentation section. Explore any dependencies that this Test folder code may have (freely spawn additional subagents to free context) and document additional components as needed.

A7. Notes on Permissions and Guardrails

Avoid broad destructive permissions unless there is a clear need.
Prefer restrictive delete/remove permissions and grant broader rights only when justified.
Make permission decisions deliberately and review them session by session where appropriate.
Treat version control as essential because Git access and rollback discipline are key safeguards.

Appendix B — Background Notes (Non-Procedural)

These notes explain why certain standards appear in the SOP. They are included as background context rather than as direct work instructions.

Enhanced PR review is emphasized because AI-assisted changes can affect architecture, maintainability, and large-scale code structure.
Persistent markdown context and plan files are emphasized because assumptions and direction need to be preserved across role handoffs rather than relying on memory alone.
Requirements enablement is intentionally prominent because development and QA can accelerate faster than requirement quality improves.
Connector and plugin guardrails are included because broader enablement without controls creates adoption and governance risk.
Mentorship and controlled rollout are included because the team is still building operational experience and does not yet want uncontrolled production usage.

Appendix C — Recommended Minimum Contents for CLAUDE.md

Project overview and purpose
Tech stack and major solution areas
Key directories and their purpose
Essential build and test commands
References to deeper documentation in .claude/docs/
Rules for updating documentation and lessons learned when material changes are made

ADLC-Compliant

Development Workflow

Agent-Driven Development Lifecycle — The complete developer hand-guide from session start to merged PR

v2.0 Optimization Applied

June 2026

Incorporates optimization review recommendations: tiered context loading (40–70% cost reduction), developer-reads-ticket-first at Step 2, strengthened gate deliverables at Step 4, Jira AC as test oracle at Step 6, Skills for glossary/FRS, CLAUDE.md under 100 lines, and trimmed prompt library.

Introduction

MCP Config

14-Step Workflow

Commands

Context Strategy

Hooks

Subagents

Prompt Library

Best Practices

Pitfalls

Governance

Task Checklist

Quick Reference

Introduction — What is ADLC?

Agent-Driven Development Lifecycle overview and pilot results

ADLC — Agent-Driven Development Lifecycle

ADLC is SunCHECK's methodology for integrating Claude Code as an AI co-developer. It structures agency into fourteen deliberate steps with defined inputs, outputs, and quality gates. The approved platform is Microsoft Foundry via Entra ID authentication; Claude Code picks up Azure CLI credentials automatically after az login.

Scope: This document operationalizes the Developer workflow of the A3C SOP for Sprint 61 and beyond.

SunCHECK is an FDA-regulated, safety-critical radiation therapy QA platform serving 5,000+ cancer centers. ADLC is not optional — it is the mandated path to ensure every AI-assisted change passes the same rigor as any traditional change. From SOP §12: The individual who submits or commits AI-assisted work remains accountable for quality, correctness, and maintainability.

Why follow ADLC?

The Sprint 60 pilot validated this workflow across twelve stories with measurable results. The data makes the case: structured AI-assisted development delivers significant time savings without sacrificing quality.

~50%

Avg Time Savings

37–80%

Range Per Task

26.5h

Total Hours Saved

6.9→7.2

Velocity Lift (SP/Dev)

Sprint 60 Pilot: Twelve stories shipped with an average ~50% time savings, ranging from 37% to 80% per task. 26.5 total developer hours were saved across the sprint. Velocity lifted from 6.9 to 7.2 story points per developer. All changes passed peer review and quality gates without rework.

Your accountability is not diminished by AI. You own every line you commit. The fourteen steps exist to keep you in control.

The 14-Step Developer Workflow

From session start to merged PR — every step with inputs, outputs, and gates

Rule: One JIRA ticket → one named session → one feature branch → one merged PR. Two mandatory gates (Steps 4 and 13). Four downstream checks (Steps 9, 10, 12, 13) loop back to Step 6 on failure.

AI-assisted step

Mandatory human review gate

Loops back to Step 6 on failure

#	Step	Driver	AI	Gate / Loop
01	Start a named session	Developer	—	—
02	Pull requirements from JIRA	Developer	●	—
03	Implementation Plan	Developer	●	—
04	Implementation Plan Review	Developer	—	● GATE
05	Update JIRA	Developer	●	—
06	Implementation & refinement cycle	Developer	●	—
07	Code cleanup	Developer	●	—
08	Update comments & documentation	Developer	●	—
09	Security review	Developer	●	↻ 6
10	SonarQube quality dashboard	Developer	●	↻ 6
11	Create PR / Commit	Developer	●	—
12	PR Review — GitHub Copilot	Developer	●	↻ 6
13	Peer Review PR	Senior Developer	●	● GATE ↻ 6
14	Merge PR, handoff & close	Developer	●	—

Click any step to expand its checklist

Start a Named Session (claude /rename)

▶

Create a resumable, named Claude Code session for the ticket. Output: Named Claude Code session bound to the JIRA ID.

Pull Requirements from JIRA

▶

Pull the full ticket — story, acceptance criteria, linked defects, history — directly into the session. Output: Story details, acceptance criteria, and linked items loaded as context.

Implementation Plan (Claude /plan)

▶

Produce a detailed, file-level implementation plan in Plan Mode — no code changes yet. Output: Implementation plan saved as .md in .claude/docs/project_plans/.

Implementation Plan Review

MANDATORY GATE

▶

Mandatory self-review of the AI-generated plan before any code is written. Output: Approved plan, or revisions that loop back to Step 3.

Update JIRA

▶

Reflect refinements from the plan review back into JIRA. Output: JIRA story updated with refined acceptance criteria.

Implementation & Refinement Cycle

LOOP POINT

▶

Execute the approved plan phase by phase. This is the return point for every failed downstream check. Output: Feature branch with new/modified code, logical commits, green build, passing tests.

Code Cleanup (Claude /simplify)

▶

Ask Claude to simplify overly complex generated code. Output: Refactored code with reduced complexity and no behavioural change.

Update Comments & Documentation

▶

Bring inline comments, API documentation, and design docs in line with the new code. Output: Inline comments, API docs, and design docs updated.

Security Review (/security-review)

↻ STEP 6

▶

Run Claude Code's built-in /security-review on pending changes. Output: Security findings report with severity and suggested fixes.

SonarQube Quality Dashboard

↻ STEP 6

▶

Push the branch through SonarQube for the consolidated quality gate. Output: Consolidated quality gate: PASS or FAIL with issue list.

Create PR / Commit (Coauthor: Claude)

▶

Open the pull request via GitHub MCP, with Claude listed as co-author. Output: Pull request opened with JIRA link, change summary, and CI triggered.

PR Review — GitHub Copilot

↻ STEP 6

▶

Automated PR review by GitHub Copilot. Output: Automated Copilot review comments on the PR.

Peer Review PR (Senior Developer)

MANDATORY GATE

↻ STEP 6

▶

Mandatory human code review by the Senior Developer, assisted by Claude's /review. Output: Approved / changes-requested with detailed review comments.

Merge PR, Handoff & Close

▶

Squash-merge the approved PR, persist handoff artifacts. Output: Merged PR; JIRA status updated; handoff artifacts persisted; lessons.md updated.

MCP Server Configuration

Model Context Protocol — connecting Claude to external tools

MCP — Model Context Protocol

MCP is Claude's integration layer with external tools. It is how Claude reads your JIRA tickets, opens pull requests, and accesses external services.

Prerequisites

(1) Install Claude Code via native installer (v2.1.86+). (2) Authenticate to Foundry: run az login. (3) Verify with claude /doctor.

Transports

Transport	When to use	Add-command shape
http	Official remote MCP (GitHub, etc.)	`claude mcp add --transport http [flags] <name> <url>`
sse	Remote MCP where HTTP isn't available. Deprecation path.	`claude mcp add --transport sse [flags] <name> <url>`
stdio	Local process — community servers, dev tools.	`claude mcp add [flags] <name> -- <command> [args...]`

Scopes

Scope	Stored in	Shared with
local (default)	`~/.claude.json`	Just you, current project
project	`.mcp.json` at repo root	Your whole team
user	`~/.claude.json` (global)	Just you, across every project

GitHub MCP

CRITICAL — REQUIRED

export GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxx
claude mcp add --transport http --scope user \
  --header "Authorization: Bearer $GITHUB_TOKEN" \
  github https://api.githubcopilot.com/mcp/
claude mcp list
claude mcp get github

SonarQube MCP

OPTIONAL

export SONARQUBE_TOKEN=<your-token>
export SONARQUBE_URL=https://sonarqube.suncheck.internal
claude mcp add sonarqube \
  --scope user \
  --env SONARQUBE_TOKEN=$SONARQUBE_TOKEN \
  --env SONARQUBE_URL=$SONARQUBE_URL \
  -- docker run -i --rm --init --pull=always \
     -e SONARQUBE_TOKEN -e SONARQUBE_URL mcp/sonarqube

Playwright MCP

OPTIONAL

npx playwright install --force
cd path/to/suncheck-repo
claude mcp add playwright \
  --scope project \
  -- npx -y @playwright/mcp@0.0.70 --headless
git add .mcp.json && git commit -m "Add pinned Playwright MCP 0.0.70"

Managing MCP Servers

claude mcp list
claude mcp get github
claude mcp remove github
> /mcp
claude mcp add-json plane '{"type":"stdio","command":"uvx","args":["plane-mcp-server"]}'

Commands & Keyboard Shortcuts

Every slash command, CLI flag, and keyboard shortcut you need

CC-2026 OPUS 4.7 (future) NOT AVAILABLE ON FOUNDRY PREVIEW DEPRECATED

Session & Navigation Commands

Command	Alt.	Description	When to use
/rename	—	Name the current session	Session start
/resume	—	Jump back into a named session	Resume work
/status	—	Confirm API usage, environment, default model	Before work
/doctor	—	Environment diagnostics	Troubleshoot
/config	—	Open interactive settings editor	Configure
/plan	Shift+Tab ×2	Enter plan mode	Task start
/clear	—	Reset context window	Between tasks
/compact	—	Compress context preserving key info	>70% context
/context CC-2026	—	Show what is loaded into context	Orient yourself
/branch CC-2026	/fork	Branch conversation into new session	Explore forks
/memory	—	View and edit CLAUDE.md and auto-memory	Session end
/export	—	Export full conversation as text	Documentation
/copy CC-2026	—	Copy Claude's output to clipboard	Share output
/add-dir	—	Add another directory to session scope	Extend scope
/effort	—	Set thinking depth: low/med/high/max (xhigh on 4.7)	Tune reasoning
/model	—	Switch models mid-session	Change model

Code Quality & Review Commands

Command	Alt.	Description	When to use
/security-review CC-2026	—	Analyze pending changes for security issues	Before commit
/review	—	Built-in code review against base branch	Step 13
/simplify	—	Refactor to reduce complexity	After impl.
/debug	—	Enable debug logging	Build failures
/diff CC-2026	—	Diff viewer for uncommitted changes	Before commit
/insights CC-2026	—	Session analytics	Retrospective
/cost	—	Token usage and cost for session	Budget check
/usage CC-2026	—	Plan-level usage limits	Capacity check

Configuration & System Commands

Command	Alt.	Description	When to use
/permissions	—	Manage allow/ask/deny rules	Harden setup
/sandbox	—	Open sandbox configuration	Regulated runs
/agents	—	Manage subagent configurations	Multi-agent
/hooks	—	Browse configured hooks	Audit hooks
/mcp	—	MCP server status + OAuth	MCP ops

CLI Flags & Keyboard Shortcuts

Command / Key	Alt.	Description	When to use
claude -w	--worktree	Launch in isolated git worktree	Parallel tasks
claude -c	--continue	Continue most recent conversation	Resume work
claude -r	--resume	Resume a specific named session	Named sessions
claude -p	--print	Non-interactive print mode	Scripting
Esc+Esc	/rewind	Browse checkpoints — restore code or conversation	Undo mistakes
Shift+Tab	—	Cycle permission modes	Mode switch
Alt+V	—	Paste screenshots/images	UI work
Ctrl+G	Ctrl+X Ctrl+E	Open prompt in $EDITOR	Edit prompt

Permission Modes (6 modes)

Mode	Behavior	Use for
default	Asks before every file change and command	Sensitive work, starting out
acceptEdits	Auto-approves file edits; still asks for commands	Iterating on reviewed code
plan	Read-only; generates a plan, makes no changes	Step 3 — always
auto	Sonnet 4.6 classifier auto-approves safe calls. Admin-enabled.	Long-running trusted tasks
dontAsk	Auto-denies anything not on allowlist	CI pipelines, locked-down
bypassPermissions	All prompts off. No prompt-injection protection.	Isolated containers only

Safety default: Stay in default or acceptEdits unless you have a specific reason. For regulated work: plan → acceptEdits (for approved plan phase) → back to default.

Context Strategy — The 3-Layer System

How Claude loads and manages project knowledge across sessions

CLAUDE.md & Path-Scoped Rules

Holds universal project rules — hard rules only. Loads in full at every session start.
Load order: Managed policy → ./CLAUDE.md → ~/.claude/CLAUDE.md → ./CLAUDE.local.md
For path-specific rules, use .claude/rules/*.md with paths: frontmatter. Target: under 100 lines. Move architecture, doc indexes, and pattern references to .claude/docs/.

Skills (On-Demand Knowledge)

Track-specific playbooks in .claude/skills/<name>/SKILL.md. Descriptions always loaded; bodies load only when invoked. Build a skill for any workflow you repeat more than once a week.

Memory (Persistent Learning)

User-authored memory (CLAUDE.md) + Auto-memory (~/.claude/projects/<project>/memory/MEMORY.md). First 200 lines or 25KB auto-load each session. End sessions with: "Update what we did to the project knowledge base."

Governing Principle (v2.0)

Context is not free. Every file loaded into a session costs tokens and competes with the ticket content for Claude's attention. Load the minimum context that makes Claude correct, not the maximum context that makes you feel safe.

Tiered Context Loading

Use this table at Step 2 to select only the files relevant to your ticket type. This reduces per-session context by 40–70% on typical tickets.

Ticket Type	Load These Files	Skip These Files
Backend feature / bug	backend.md	frontend.md, module_map.md
Frontend / UI	frontend.md	backend.md, module_map.md
Database / schema change	databases.md, backend.md	frontend.md, module_map.md
Cross-cutting refactor	module_map.md, backend.md	frontend.md
Domain-specific (dose, auth, audit)	glossary.md, frs.md + relevant module file	module_map.md unless cross-cutting
Test coverage only	Relevant module file only	glossary.md, frs.md, module_map.md
Doc / config only	None beyond CLAUDE.md	All .claude/docs/ files

Recommended Skills (On-Demand Context)

Convert these heavy context files to Skills so they load only when Claude needs them, not at session start.

Skill Name	Trigger	Loads
domain-glossary	When Claude needs RT QA terminology or domain term clarification	glossary.md
requirements-lookup	When checking acceptance criteria against FRS or verifying a business rule	frs.md
lessons-review	At session start on tickets in a previously-worked area	lessons.md (filtered by relevant domain)

CLAUDE.md Target: Under 100 Lines

Every line in CLAUDE.md loads on every session — including routine bug fixes. Apply this test: "If I removed this line, would Claude make a wrong decision on every single ticket?" If not, move it to .claude/docs/ or convert it to a Skill.

Move out of CLAUDE.md: Architecture diagrams → .claude/docs/architecture.md | Service boundaries → same file | 9-file doc index → replace with 3-line summary
Evaluate keeping: Quick Reference patterns (DI, logging, current user, audit, soft delete) — keep only if Claude violates them without the reference.

SunCHECK Context Files

suncheck-repo/ ├── CLAUDE.md # Layer 1 — project policy + doc index ├── .claude/ │ ├── settings.json # Hooks configuration │ ├── docs/ │ │ ├── backend.md # 151 controllers + middleware chain │ │ ├── frontend.md # Vue (7 modules), Knockout, page tree │ │ ├── databases.md # 16 entity domains │ │ ├── module_map.md # ~250 projects, dependency flow │ │ ├── dependencies.md # NuGet/npm + 28 shared libs + CI/CD │ │ ├── glossary.md # ~155 RT QA domain terms │ │ ├── frs.md # 57 requirements across 21 domains │ │ ├── lessons.md # Team learnings + anti-patterns │ │ └── project_plans/ # Saved implementation plans │ ├── skills/ # Reusable workflows (Layer 2) │ ├── agents/ # Custom subagents │ └── memory.jsonl # Memory MCP storage └── ...

lessons.md (SOP §6.4 — Required Shared Artifact)

Per A3C SOP §6.4, lessons.md is a required shared artifact. It captures recurring issues, debugging lessons, anti-patterns, and team learnings. Commit updates whenever you discover something that would change how others prompt, code, debug, or test.

Handoff Artifacts (SOP §6.5)

When AI-assisted work moves between roles, the minimum persisted artifacts are: CLAUDE.md updates, .claude/docs/ updates, active project plan, lessons.md updates.

Hooks & Automation

Deterministic enforcement via settings.json hook events

"Unlike CLAUDE.md instructions which are advisory, hooks are deterministic and guarantee the action happens." For anything that must happen every time — formatters, audit-log emission, test gates — use a hook.

Hook Events

Event	Cadence	Common use
SessionStart	Per session	Inject branch/ticket context; audit-log
UserPromptSubmit	Per turn	Validate prompts; enforce context
PreToolUse	Per tool call	Security gate — exit 2 blocks the call
PostToolUse	Per tool call	Auto-lint, format, emit audit event
Stop	Per turn	Run tests, emit session-end events
SessionEnd	Per session	Archive artifacts; flush audit buffer

Correct settings.json Schema

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs -r npx prettier --write"
          }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "bash scripts/guard.sh"
          }
        ]
      }
    ]
  }
}

stdin Contract

Hook scripts receive JSON on stdin. No template variables. Common fields: .tool_name, .tool_input, .tool_response, .session_id, .cwd

Exit Codes

exit 0 = allow
exit 2 = block (on PreToolUse, tool call denied)
any other non-zero = log warning

Handler Types

command (shell — fastest) http (POST to endpoint) prompt (Claude evaluation) agent (launches subagent)

Subagents & Git Worktrees

Isolated investigation agents and parallel working copies

Subagents — Isolated Investigation

Subagents run in their own context with their own tool permissions. Three built-in: general-purpose, Explore (fast, read-only), Plan (research for plan mode).

Custom Subagent Example (.claude/agents/security-reviewer.md)

---
name: security-reviewer
description: Reviews diff for OWASP Top 10 and regulated-device concerns
model: opus
effort: xhigh
isolation: worktree
tools: [Read, Grep, Glob]
---

Review the code in the current branch for OWASP Top 10 vulnerabilities.
Flag injection risks, auth flaws, secrets in code, and unsafe deserialization.

Routines

Routines are scheduled background tasks that run on a timer. Use them for automated PR monitoring, dependency checks, or recurring quality sweeps. Note: Routines require Claude.ai auth and are not available on Foundry.

# Schedule a routine (requires Claude.ai auth)
/schedule every 30m "Check open PRs for stale reviews"
/schedule daily "Run dependency audit on main branch"

Git Worktrees

Run multiple Claude sessions simultaneously. Each worktree gets an isolated working copy.

claude --worktree feature-auth
claude --worktree feature-auth --tmux
git worktree list
git worktree remove <path>

REVIEW.md — Hard-Stop Review Rules

For the automated Code Review feature. Unlike CLAUDE.md (general context, violations become nits), REVIEW.md content is injected at highest priority. Use for safety-critical, hard-stop rules: dose-calc boundaries, SSO/auth invariants, audit-log completeness.

Prompt Library

Ready-to-use prompt templates for every phase of the workflow

Planning — Feature Implementation

Implement [JIRA ticket ID]: [brief description].
Scope: [files/modules in play].
Create a plan covering:
- Files to change and order of implementation
- Test strategy per acceptance criterion
- Risks and edge cases
Do not implement yet.

Planning — Architecture Decision

I'm evaluating approaches for [feature/change].
Read the following files to understand the current architecture:
- [file1]
- [file2]
Compare these approaches:
1. [Approach A]
2. [Approach B]
For each, analyze: implementation complexity, impact on existing tests,
performance implications, and alignment with our current patterns.
Recommend one with reasoning. Do not write any code yet.

Impact Analysis

Pull JIRA ticket [ID] and analyze requirements. Identify all affected files,
dependencies, breaking change risks, and required test updates.
Load context files per the tiered loading table for this ticket type.

Implementation with Verification

Implement [feature] following the patterns in [reference file].
Use [framework], follow coding standards in CLAUDE.md, and include unit tests.
After implementing, run the test suite and fix any failures.
Verify the build succeeds. Address root causes — don't suppress them.

Test Generation

Generate comprehensive test cases for [ticket ID] covering:
- Happy path scenarios matching each acceptance criterion
- Edge cases: [specific edge cases if known]
- Error handling and boundary conditions
Include setup, assertions, and teardown. Run the tests after generating
them and fix any failures.

Code Review (Fresh Session)

Review the changes on this feature branch against [target branch]. Check for:
- Coding standard violations per CLAUDE.md
- Security vulnerabilities (injection, auth flaws, secrets)
- Missing test coverage for new/changed behavior
- Performance concerns
- Architectural alignment with existing patterns
Provide specific line references and suggested fixes.

PR Creation via GitHub MCP

Create a pull request for this branch. Include:
- Summary of changes organized by component
- Affected files and modules
- Test coverage for new behavior
- Any migration notes or deployment considerations
Use co-author attribution for Claude Code contributions.

SonarQube Remediation (SonarQube MCP)

Check the SonarQube quality gate status for PR [number] on project [key].
If the gate is FAILED:
1. List every new issue grouped by severity.
2. For CRITICAL or BLOCKER issues, pull the full finding and apply the fix.
3. For security hotspots, review and fix or mark safe with justification.
4. Re-trigger analysis and confirm the gate passes.
Do not modify any file outside this branch's changes.

Best Practices

15 proven practices from the SOP, pilot retrospectives, and Anthropic guidance

Practice	Description	Source
You Own the Commit	The person who submits AI-assisted work remains accountable. Review every line.	SOP §12
Maintain Requirement Traceability	JIRA ticket → commits → PR. Use JIRA ID in branch name.	SOP §12
Persist the Handoff	Commit CLAUDE.md, .claude/docs/, plans, lessons.md when they affect future work.	SOP §6.5, §13
One Task = One Session	Keep sessions focused. At 90% context, performance degrades. Use /clear between tasks.	Anthropic Docs
Story-Level Work Items	Assign complete stories that exercise all fourteen steps.	Pilot Retrospective
Hooks Over Instructions	Hooks are deterministic; CLAUDE.md is advisory. Use hooks for enforcement.	Anthropic Docs
Checkpoints Are Free Undo	Esc+Esc opens rewind. Try risky approaches knowing you can roll back.	Anthropic Docs
Subagents for Investigation	Delegate research to subagents — they keep your main session clean.	Anthropic Docs
Worktrees for Parallelism	claude --worktree for multiple features simultaneously.	Anthropic Docs
Skills Over Repeated Prompts	If you do something more than once a week, make it a skill.	Anthropic Docs
Verify, Verify, Verify	Give Claude a way to verify its own work. Include test commands.	Anthropic Docs
Co-Author Attribution	Tag PRs as co-authored for AI contribution tracking.	Pilot Retrospective
Progressive Disclosure	Explore first, then plan, then implement.	Anthropic Docs
Tiered Context Loading	Load only the context files relevant to your ticket type — not all files on every session. See Context Strategy table.	v2.0 Optimization
Track Every Session	Log time saved per ticket. Use /insights for analytics.	SOP §15 + Pilot

Common Pitfalls & Fixes

Avoid these mistakes and troubleshoot common issues

Avoid

Jumping into Claude without reading the JIRA ticket first — letting Claude summarize requirements you haven't read yourself.

Instead

Read the ticket yourself first. Understand the AC, context, and linked defects. Then have Claude confirm your understanding, not establish it.

Avoid

Loading all .claude/docs/ files on every ticket (the single largest avoidable cost driver).

Instead

Use the Tiered Context Loading table — load only the files relevant to your ticket type.

Avoid

Running one long session across multiple unrelated tasks.

Instead

One task per session. Use /clear or start fresh.

Avoid

Accepting Claude's plan or code without critical review.

Instead

Plans and code are starting points. Review critically.

Avoid

Skipping verification because the code compiles.

Instead

Run full test suite, lint checks, and requirement traceability.

Avoid

Putting everything in CLAUDE.md — architecture diagrams, doc indexes, pattern references all load on every session.

Instead

Target under 100 lines. Move architecture + doc index to .claude/docs/. Convert glossary & FRS to Skills. Use hooks and .claude/rules/*.md.

Avoid

Not using checkpoints when trying risky approaches.

Instead

Esc+Esc shows checkpoints. Try, rewind if it fails.

Avoid

Not logging effort and time savings after each session.

Instead

Update productivity tracker. Use /insights and /cost.

Avoid

Calling budget_tokens in API code on Opus 4.7.

Instead

Use /effort or the effort parameter. Returns HTTP 400 on 4.7.

Avoid

Expecting ${file} expansion in hook commands.

Instead

Hooks receive JSON on stdin. Parse with jq.

Troubleshooting

Symptom	Likely cause	Fix
claude command not found	Installer not on PATH	Check `which claude`. Re-run installer.
"Authentication failed"	Foundry Entra token expired	Run `az login` again
/doctor reports MCP failures	Server config or network	Run `claude mcp list`, remove and re-add
Hook not firing	Not registered or wrong event	Run `/hooks` to see registered hooks
/effort xhigh returns error	Opus 4.7 not available	Use `/effort high` or `/effort max`
Plan file not auto-loading	Outside memory hierarchy	CLAUDE.md auto-loads; plans load when referenced

Governance & Audit

Permission modes, settings precedence, and platform availability

Permission Modes — SunCHECK Approved Usage

Mode	Behavior	Approved for
default	Asks before every file change	All SunCHECK work (safe default)
acceptEdits	Auto-approves edits; asks for commands	Iterating on reviewed plan (Step 6)
plan	Read-only; generates plan	Step 3 — always
auto	Sonnet 4.6 classifier. Admin-enabled.	Long-running investigation in sandbox
dontAsk	Auto-denies anything not on allowlist	CI/headless/locked-down
bypassPermissions	All prompts off. No injection protection.	Isolated containers/VMs only

settings.json Precedence

Tier	Location
Managed policy	`/etc/claude/managed-settings.json` (Win: `%ProgramData%\Claude\`)
Project	`.claude/settings.json` (commit this)
User	`~/.claude/settings.json`
Local	`.claude/settings.local.json` (not committed)

Declarative Tool Permissions Example

{
  "permissions": {
    "allow": [
      "Read", "Grep", "Glob",
      "Bash(git status:*)", "Bash(git diff:*)",
      "Bash(npm test:*)", "Bash(dotnet test:*)"
    ],
    "deny": [
      "Bash(rm -rf:*)", "Bash(git push --force:*)",
      "Write(src/dose/**)", "Edit(src/dose/**)",
      "Read(.env)", "Bash(cat .env:*)"
    ]
  }
}

Note: Deny always wins over allow. Bash patterns use prefix matching.

Foundry Availability Matrix

Feature	Available on Foundry	Notes
Haiku 4.5, Sonnet 4.6, Opus 4.6	✓	—
Opus 4.7	Depends on deployment	Check Foundry admin
/effort xhigh	With Opus 4.7 only	—
/ultrareview, /ultraplan	✗	Requires Claude.ai auth
Routines (/schedule)	✗	Requires Claude.ai auth
/review, /security-review, /plan	✓	—
/insights, /loop, /doctor, /sandbox	✓	—
Subagents, Skills, Hooks	✓	—
MCP servers, Git worktrees	✓	—
Plan mode, Checkpoints	✓	—

Task Checklist

Per-ticket checklist covering all 14 steps — copy and work top-to-bottom

Copy this checklist at the start of each ticket. Work top-to-bottom. If you bounce back to Step 6, re-start downstream steps (9, 10, 12, 13) from scratch.

Start a named session

☐ Run claude /doctor to confirm installation, login, Node 22+, MCP health
☐ Run claude /config to confirm settings.json merged correctly
☐ Start Claude in repo root: claude
☐ Run /rename <JIRA-ID>-short-desc to name the session
☐ Verify CLAUDE.md and context files auto-loaded via /context

Pull requirements from JIRA

☐ Read the JIRA ticket yourself first — understand AC, context, linked defects before Claude
☐ Load JIRA ticket details including linked items
☐ Confirm all acceptance criteria are present
☐ Load context files by ticket type (see Tiered Context Loading in Context Strategy)
☐ Create feature branch: feature/JIRA-XXXX-short-desc

Implementation Plan

☐ Enter Plan Mode (Shift+Tab ×2)
☐ Ask Claude to explore relevant files
☐ Request plan: files, order, test strategy per AC, risks
☐ Open plan in VS Code and refine directly
☐ Save plan to .claude/docs/project_plans/JIRA-XXXX-plan.md

Plan Review

GATE

☐ Read the plan end-to-end with a critical eye
☐ Confirm every file-level change has sound rationale
☐ Confirm safety-critical + regulatory items addressed
☐ Confirm every AC has a test strategy
☐ Check edge cases, error handling, rollback paths
☐ Write one sentence per AC explaining how the plan addresses it
☐ Identify the riskiest file change and write down why it is safe
☐ Sign the plan: # Reviewed: [JIRA-ID] [date] [initials]

Update JIRA

☐ Update JIRA description with clarified scope
☐ Adjust acceptance criteria if review revealed gaps
☐ Move ticket to In Progress; link feature branch

Implementation cycle

AI · LOOP POINT

☐ Switch to Normal Mode (Shift+Tab)
☐ Execute plan one phase at a time
☐ Review every line of generated code
☐ Commit after each logical unit
☐ Run build locally — fix errors immediately
☐ Run unit test suite — no skipped or failing tests
☐ Address root causes, not symptoms
☐ Before each commit: check off JIRA ACs your commit satisfies

Code cleanup

☐ Run /simplify on changed files
☐ Review every refactor
☐ Re-run unit tests; verify zero behavioral change
☐ Commit cleanup as separate logical commit

Documentation

☐ Update inline comments for non-obvious logic
☐ Regenerate API docs if signatures changed
☐ Update affected design docs or ADRs

Security review

AI · ↻6

☐ Run /security-review in session
☐ Review each finding and remediation
☐ Fix confirmed issues
☐ If non-trivial — loop to Step 6

SonarQube

AI · ↻6

☐ Trigger SonarQube analysis on feature branch
☐ Verify quality gate: PASS
☐ Meet coverage threshold on new code
☐ Capture quality-gate screenshot for PR

Create PR

☐ Generate PR description from plan + commits
☐ Confirm Co-authored-by: Claude trailer present
☐ Link JIRA ticket in PR body
☐ Attach security-review and SonarQube results
☐ Open PR; confirm CI starts

Copilot Review

AI · ↻6

☐ Wait for Copilot review to complete
☐ Triage comments: accept, reject, defer
☐ Fix accepted comments on branch
☐ Re-push; confirm CI stays green

Peer Review

GATE · ↻6

☐ Senior Dev opens FRESH session
☐ Senior Dev runs /review on branch
☐ Manual walkthrough of safety-critical paths
☐ For high-risk: invoke security-reviewer subagent
☐ Verify requirement traceability
☐ Developer addresses every comment
☐ If non-trivial — loop to Step 6

Merge & Close

☐ Confirm CI green and reviews approved
☐ Squash-merge with JIRA ID in message
☐ Delete feature branch
☐ Update JIRA status
☐ Commit handoff artifacts
☐ Update lessons.md
☐ Run /memory to persist session learnings

Quick Reference Card

Essential commands, shortcuts, milestones, and golden rules at a glance

Essential Commands

/plan · /effort · /review · /security-review · /simplify · /doctor · /clear · /compact

Keyboard Shortcuts

Shift+Tab · Esc+Esc · Ctrl+G · Alt+V · Cmd+Esc · claude -c · claude -w · claude -r

Key Milestones

Step 3 · Plan Mode
Step 4 · GATE — Plan self-review
Step 6 · Implement · loop point
Step 9 · /security-review
Step 10 · SonarQube quality gate
Step 11 · PR with Co-author: Claude
Step 13 · GATE — Peer Review
Step 14 · Squash-merge + /memory

MCP Servers

github · REQUIRED — HTTP, --scope user
sonarqube · OPTIONAL — quality gates (Step 10)
playwright · OPTIONAL — browser automation

THE FIVE GOLDEN RULES

JIRA first. Always. No ticket, no work.

One task, one session. /clear between unrelated tasks.

Plan before code. Planning is Claude's strongest phase.

Verify before review. Hooks + tests + traceability.

Close the loop. Update memory + productivity tracker.

"The gap to close is not tooling — it's adoption discipline."

ATLC — Agent-Driven Testing Lifecycle

Phases 0–13 | Manual + Automation | SunCHECK QA Agent System | suncheck-qa-agents/

Dashboard

ATLC Workflow

▶ ATLC Workflow Pipeline (Phases 0 – 13)

Plan/Review (no files)

Human Gate

Write/Execute (files generated)

Automation Phase

Cost Checkpoint

Manual (post-AI)

Phase 0-1

Session Start

CLAUDE.md
guardrails

▶

Phase 2–4

Intake + Context + Plan

/analyze-story

■ START snapshot

▶

Gate 1

CONFIRM PLAN

user approves plan

▶

Phase 5

Write TCs

/write-tests

▶

Phase 6

AI Self-Review

/review-tests

▶

Gate 2

APPROVE TCs

user approves TCs

▶

Phase 7

Export .csv

/export-tests
Zephyr format

▶

Phase 8

Upload to Zephyr

/upload-tests

▶

Gate 3

RA REVIEW

mandatory

▶

Phase 9

Alignment

/generate-alignment

↳ continues below

Gate 4

APPROVE ALIGN

approve / fix / cancel

▶

Phase 10

Automation Code

/generate-spec

▶

Phase 11

AI Code Review

/automation-review

▶

Gate 5

APPROVE CODE

approve / fix / cancel

▶

Phase 12

Final Code Delivery

/automation-deploy

■ END snapshot

▶

Session Close

Cost Summary

/cost

▶

Phase 13

Execute, Debug & PR

manual

▶

Gate 6

CODE REVIEW

human review & merge

⚙ Skill Map

/generate-tests
Master Orchestrator — chains all 11 sub-skills (Phases 0–12)

/analyze-story
Phases 2-4

/write-tests
Phase 5

/review-tests
Phase 6 + Gate 2

/export-tests
Phase 7

Automation Skills (Phases 9–12)

/generate-alignment
Phase 9

/generate-spec
Phase 10

/automation-review
Phase 11

/automation-deploy
Phase 12

/cost
Session Log

/upload-tests
Phase 8

💰 Cost Tracking — cost_snapshot.js

          <KEY> start — START snapshot at Phase 2  
          <KEY> end <TC-KEY> — END snapshot at Phase 12  
          report [KEY] — cost for story / TC / all

          output/cost_ledger.csv (source of truth)  | 
          output/cost_ledger.md (human-readable)
        

Reference Files

        self-review-checklist.md (6A/6B/6C)

        automation-rules.md (9 rules)

        scenario-categories.md (H/N/P/D/E/X)

📁 AI Artifacts

SunCHECKQA_Agent_CL/
├─ CLAUDE.md project brain
├─ corrections-log.md mistake log + CT-ID anti-patterns (loaded Phase 3)
├─ session-log.md session summaries (/cost)
├─ .claude/skills/ 11 skill files
│ ├─ generate-tests/ orchestrator (phases 0-12)
│ ├─ analyze-story/ phases 2-4
│ ├─ write-tests/ phase 5
│ ├─ review-tests/ phase 6 + gate 2
│ ├─ export-tests/ phase 7
│ ├─ upload-tests/ phase 8
│ ├─ generate-alignment/ phase 9
│ ├─ generate-spec/ phase 10
│ ├─ automation-review/ phase 11
│ ├─ automation-deploy/ phase 12
│ └─ cost/ session log (/cost skill)
├─ context/ 27 domain files
│ ├─ navigations.md UI paths
│ ├─ glossary.md 60+ terms
│ ├─ lessons.md team insights
│ ├─ machine/ 6 files
│ ├─ patient/ 6 files
│ ├─ platform/ 5 files
│ └─ services/ 6 files
├─ output/ generated files
│ ├─ *.xlsx Zephyr exports + PLAN files
│ ├─ cost_ledger.csv per-story cost (source of truth)
│ ├─ cost_ledger.md human-readable cost view
│ ├─ cost_snapshot.js cost tracking engine
│ └─ *.spec.ts automation code

📚 Context Files — Domain Knowledge Base

Each module: _index.md (routing table) → sub-files (topic-specific). Agent loads _index first, then follows routing table.

Machine (6 files)

_index.md → routing table
snc-machine.md → W/L, DIN, baseline
snc-routine.md → templates, TG-142
devices.md → DQA3, ICP, PCE
opal-dqa4.md → Opal Imaging QA
machine-2.md → Quick QA, Logbook

Patient (6 files)

_index.md → routing + shared flows
perfraction.md → Fx0/FxN, EPID/Log
dosecheck.md → 3D dose, gamma
plancheck.md → DVH, point dose
devices.md → ArcCHECK, EPID
specialty.md → AdaptCHECK, brachy

Platform (5 files)

_index.md → routing + arch + install
auth.md → AAD/AD, roles, perms
admin.md → licensing, SSL, prefs
infrastructure.md → DB, jobs, logging
deployment.md → SC Local, SSRS

Services (6 files)

_index.md → routing + inventory
dicom.md → Listener, Q/R
file-monitor.md → folder watchers
icom.md → Elekta/ICOM VX
data-pipeline.md → provisioning, R&V
processing.md → Staging Queue, jobs

Shared: navigations.md | glossary.md | lessons.md | corrections-log.md

Phase 3 — Context Loading Sequence

        1. navigations.md — UI paths for test steps

        2. glossary.md — domain terms (if unfamiliar)

        3. lessons.md — team insights from prior sessions

        4. corrections-log.md — mistake log + CT-ID anti-patterns (scan for matching module/category)

        5. module/_index.md — routing table → sub-files

        6. automation repos — Puppeteer + Playwright (for Phases 9–12)

Written at session close: lessons.md — append lessons | cost_ledger.csv — per-story cost (END snapshot) | session-log.md — session summary (/cost)

🔧 Correction & Learning

Agent Corrections

User corrects
mistake

→

corrections-log.md
(append entry)

→

Fix in relevant
SKILL.md
(rule enforced at source)

3+ same category â†’ promote to CT-ID section in corrections-log.md with root cause + skill files changed

Team Lessons

Session discovery

→

context/lessons.md
(append-only)

lessons.md loaded at Phase 3 | appended at Session Close
corrections-log.md loaded at Phase 3 | appended when mistake found; CT-ID promoted when 3+ same category
cost_ledger.csv updated at Phase 12 (END snapshot) | session-log.md written at Session Close (/cost)

🔗 External Integrations

Jira REST API

sncapps.atlassian.net
Basic auth (session-only token)
Used by: /analyze-story (Phase 2)

Zephyr Scale API

api.zephyrscale.smartbear.com/v2
Bearer token (ZEPHYR_SCALE_TOKEN)
Used by: /upload-tests (Phase 8)

Automation Repos

GitHub_SunCHECK_Automation (Puppeteer)
sc-playwright-automation (Playwright)
Used by: Phases 9–12

Node.js + SheetJS

xlsx package (v18.16.1)
Used by: /upload-tests (Phase 8)

ATLC Workflow

Agent-Driven Testing Lifecycle — from Jira story to deployed automation code

AI-Driven

Tester (Manual)

Collaborative

Mandatory Gate

Click any phase to expand details

🚀 Session Start & Governance

AUTO

▶

CLAUDE.md auto-loads. 10 guardrails, output contract, skill map, and context file routing established. Cost baseline snapshot taken.

CLAUDE.md Auto-Loads

10 Guardrails — Software QA only, never invent behavior, evidence priority, Zephyr format, read before write, scenario-level steps, observable results, no login, no over-engineering, preconditions + objective mandatory
Output Contract — Name, Priority, Component, Labels, Coverage, Preconditions, Objective, Step Table
Skill Map — 11 skills chained by /generate-tests orchestrator

Cost Baseline

node phase-cost.js snapshot — saves current token count before any work begins

2â€“4

📦 Intake + Context + Plan

COLLABORATIVE

▶

Phase 2: Read Jira story. Phase 3: Load context files. Phase 4: Map ACs → R1â€“Rn, identify scenarios, confirm plan at Gate 1. Skill: /analyze-story | Cost START snapshot taken.

Phase 2 â€” Intake

Read story via Jira API or pasted content. Extract from: Description, Validation section, Notes section, Comments, Linked Bugs, Attachments (UI mockups). Identify module: Patient / Machine / Platform / Services.

Phase 3 â€” Context Loading (always load)

1. navigations.md — UI paths
2. glossary.md — domain terms
3. lessons.md — team insights from prior sessions
4. corrections-log.md — past agent mistakes + CT-ID anti-patterns
5. module/_index.md → topic-specific sub-files (6 per module)
6. Automation repos (Puppeteer + Playwright) — for Phases 9â€“12

Phase 4 â€” Analysis & Plan

4Aâ€“4B: AC â†’ Testable Behaviors â†’ R1â€¦Rn (each traces to â‰¥1 TC step)
4C: Scenario categories: [H]Happy [N]Negative [P]Permissions [D]Data [E]Edge [X]Cross-module
4D: Evidence gate (Jira AC > Zephyr TCs > Context files > Guides > Code). Gaps â†’ [TBD]
4Eâ€“4F: Step decomposition, gap analysis, confirm plan at Gate 1

🛑 Gate 1 — Confirm Plan

MANDATORY

User reviews and approves the analysis plan before test case writing begins. Reject → loop back to Phase 4.

✍️ Write Test Cases

AI PRIMARY

▶

ONE TC per story with all scenarios as steps. Each scenario = one Zephyr step with numbered sub-actions and expected results. Skill: /write-tests

Pre-Write Checklist

1. Read corrections-log.md (past mistakes + CT-IDs)
2. Verify Phase 4 plan is confirmed at Gate 1
3. Ask user review preference: (a) Screen (b) File .md (c) Both (d) Excel .xlsx with 5 sheets

Output Format

ONE TC per story. Name, Priority, Component, Labels, Coverage, Preconditions (combined), Objective (combined), Step table.
Each scenario = ONE step with numbered sub-actions + numbered expected results. Test Data = plain values or None.
Gaps â†’ [TBD â€” evidence needed: <what>]

Review Format Options

(a) Screen only — conversation display
(b) File only — output/<KEY>_Test_Cases_PLAN.md
(c) Both — screen + .md file
(d) Excel — output/<KEY>_Test_Cases_PLAN.xlsx (5 sheets: Summary, TC Metadata, Test Steps, AC Coverage, Gaps)

🤖 AI Self-Review

AI PRIMARY

▶

3-part quality gate: 6A Completeness, 6B Quality, 6C Traceability. Must-fix findings block Gate 2. Skill: /review-tests

6A. Completeness

☑ Every AC has ≥1 TC ☑ Linked bugs covered ☑ Happy path per AC ☑ Negative/error TCs ☑ Permissions (if applicable) ☑ Cross-module regression

6B. Quality

☑ Observable expected results ☑ Nav paths match navigations.md ☑ No invented behavior ☑ No duplicate scenarios ☑ Scenario-level steps (not atomic)

6C. Traceability

☑ Coverage → Jira key ☑ Component → Module ☑ Labels → Zephyr ☑ Folder path correct

🛑 Gate 2 — Human Review & Approve TCs

MANDATORY

QA Engineer reviews TCs (screen or Excel). Corrections applied iteratively. No files generated until user approves. Reject → loop back to Phase 5.

📄 Export .csv

AI PRIMARY

▶

Generate .csv (Zephyr format, importable). Skill: /export-tests

Output

Sheet 1 — INPUT: Story key, title, module, ACs (one per row)

Sheet 2 — Test Cases: 16 columns. Row 2 = all metadata + step 1. Rows 3+ = step # + step cols only.

▰ Upload to Zephyr

AI PRIMARY

▶

Push TCs to Zephyr Scale via API or manual import. Post-upload verification. Cost END snapshot taken here. Skill: /upload-tests

Upload Options

(a) Direct Zephyr API upload (POST /v2/testcases) — includes post-upload verification
(b) Export .xlsx for manual import into Zephyr Scale

Version Management

When updating an existing TC: create new version FIRST in Zephyr UI (+icon), then push API changes. Always include all custom fields in PUT payload.

🛑 Gate 3 — RA Review

MANDATORY

RA reviews uploaded TC in Zephyr and approves or requests changes. Mandatory gate — no files proceed to automation without approval. Reject → loop back to Phase 5 or 7.

🔗 Alignment

AI-DRIVEN

▶

Map approved TC steps to Playwright code + expected result assertions. Reads both Puppeteer and Playwright repos. Skill: /generate-alignment

Alignment Table

TC Step # → Action → Playwright Code → Expected Result Assertion → Status (Ready / PORT NEEDED / TBD)

🛑 Gate 4 — Approve Alignment

MANDATORY

User reviews alignment table. Approve → Phase 10. Fix <row#> → re-display updated alignment. Cancel → STOP automation.

💻 Automation Code Generation

AI-DRIVEN

▶

Alignment rows → .spec.ts file. Each row = one test() block. Reads 10 dependency files from Playwright repo. Skill: /generate-spec

Code Pattern

test.describe.serial, chromium.launch, ensurePage() recovery, imports from ../../helpers/ depth
9 automation rules from automation-rules.md applied

🔎 AI Code Review

AI-DRIVEN

▶

21-point checklist + Silent Pass Audit. Findings: Blocker / Warning / Suggestion. Skill: /automation-review

21-Point Checklist

Structure (1-5): Function patterns, scope, import depth/order, lifecycle hooks
Selectors (6-10): PO exists, selector exists, label over index, no hardcoded CSS, container scoping
Interactions (11-15): Click method, waitForFindIndexContains, no assert for UI waits, explicit timeouts, page.reload
Screenshots (16-18): Standard method, high-impact only, descriptive titles
Data & Deps (19-21): testData/ folder, params file, no duplicate methods

Silent Pass Audit

Empty test blocks, click without assert, assertion on empty string, waitForVisible on always-visible element, dropdown without verify, TODO-only blocks

🛑 Gate 5 — Approve Code

MANDATORY

User reviews generated .spec.ts after AI Code Review. Approve → Phase 12. Fix <what> → re-generate. Cancel → STOP automation.

📦 Final Code Delivery

AI-DRIVEN

▶

Apply review fixes, deliver final .spec.ts to sc-playwright-automation repo. Automation code deploy. Cost END snapshot taken here. Skill: /automation-deploy

Delivery Options

(a) Deploy to provided repo path only
(b) Download to output/ + deploy to repo
(c) Screen only â€” display for manual copy-paste

Cost END Snapshot

node output/cost_snapshot.js <KEY> end <TC-KEY> â€” captures full cost from Phase 2 intake through Phase 12 delivery. Query: report <KEY>

💰 Session Close

ALWAYS RUNS

▶

Cost END snapshot safety-net check → append lessons to lessons.md → run /cost to write session-log.md.

Cost Safety Net

Run node output/cost_snapshot.js report â€” if any story shows STARTED (no END), take END snapshot now before closing.

Lessons

Append non-obvious lessons to context/lessons.md (format: Date, Context, Lesson, Action, Tags). Only what actually happened this session.

Session Log

Run /cost → writes session summary to session-log.md (date, stories, phases, cost, TODOs).

⚙ Execute, Debug, PR & Merge

MANUAL

▶

Run automation script locally, debug and fix failures, raise PR, human code review, and merge. All manual — no AI skill.

Execute & Debug

Run .spec.ts locally against test environment. Fix selector issues, timing problems, PORT NEEDED gaps. Iterate until all tests pass.

Raise PR

Create pull request in sc-playwright-automation repo with the new/updated .spec.ts file.

🛑 Gate 6 — Code Review & Merge

MANUAL

Team reviews PR for code quality, test reliability, selector safety. Approve → merge to main. Reject → fix and re-submit PR.

ATLC Workflow Summary

0	Session Start	CLAUDE.md auto-loads with 10 guardrails, output contract, and skill map. (Governance first)
2â€“4	Intake + Context + Plan	Phase 2: Read story (ACs, Validation, Notes, Comments, Bugs, Attachments). Phase 3: Load navigations, glossary, lessons.md, corrections-log.md, module/_index.md. Phase 4: Map ACs â†’ R1â€¦Rn, 6 scenario categories, evidence gate, gaps â†’ [TBD]. Confirm plan at Gate 1. Cost START snapshot. Skill: `/analyze-story`
5	Write TCs	ONE TC per story, all scenarios as steps. Each step = numbered sub-actions + expected results. Conversation output only — no files yet. (Execute the plan)
6	AI Self-Review	3-part quality gate: completeness, quality, traceability. Must-fix findings block Gate 2. (AI self-check)
G2	Human Review	QA Engineer reviews, corrects, approves. No files generated until user approves. Reject → Phase 5. (Mandatory human gate)
7	Export .csv	Generate .csv (Zephyr format, importable). (Generate the file)
8	Upload to Zephyr	Push TCs to Zephyr Scale via API or manual import. Post-upload verification. Cost END snapshot taken here. (Deliver to Zephyr)
G3	RA Review	RA reviews uploaded TC in Zephyr and approves or requests changes. Mandatory gate — no automation proceeds without approval. Reject → loop back to Phase 5 or 7. (Mandatory gate)
9	Alignment	TC steps â†’ Playwright alignment table (Step # â†’ Action â†’ Code â†’ Expected Result â†’ Ready/PORT NEEDED/TBD). Reads Puppeteer + Playwright repos. Skill: `/generate-alignment`
G4	Approve Alignment	Approve â†’ Phase 10. Fix <row#> â†’ re-display. Cancel â†’ STOP. (Mandatory gate)
10	Automation Code	Alignment rows â†’ .spec.ts. One test() block per alignment row. 10 dependency files read. 9 automation rules applied. Skill: `/generate-spec`
11	AI Code Review	21-point checklist (Structure, Selectors, Interactions, Screenshots, Data) + Silent Pass Audit. Blocker / Warning / Suggestion. Skill: `/automation-review`
G5	Approve Code	Approve â†’ Phase 12. Fix <what> â†’ re-generate. Cancel â†’ STOP. (Mandatory gate)
12	Final Code Delivery	Apply review fixes, deploy .spec.ts to sc-playwright-automation repo. Automation code deploy. Cost END snapshot taken here. Skill: `/automation-deploy` (Ship the code)
CLOSE	Session Close	Cost safety-net check â†’ append lessons.md â†’ run /cost â†’ session-log.md written. Always runs regardless of last phase.
13	Execute & Merge	Run .spec.ts locally, debug failures, raise PR. Manual â€” no AI skill.
G6	Code Review & Merge	Team reviews PR. Approve â†’ merge to main. Reject â†’ fix + re-submit. Manual gate. (Final merge)

A3C Claude Code SOP

A3C Claude Code SOP

Document Control

Table of Contents

1. Purpose

2. Scope

3. Definitions

4. Roles and Responsibilities

4.1 TPM Responsibilities

4.2 Developer Responsibilities

4.3 QA Responsibilities

4.4 Reviewers / Technical Leads / Architects

4.5 A3C / Governance Responsibilities

5. Core Operating Standards

6. Required Shared Artifacts

6.1 CLAUDE.md

6.2 Supporting Documentation in .claude/docs/

6.3 Project Plans

6.4 lessons.md

6.5 Persisted Handoff Artifacts

7. TPM Workflow — Requirements and Problem Definition

8. Developer Workflow — Analysis, Planning, Implementation, and Documentation

9. QA Workflow — Manual and Automated Test Authoring

10. Prompting and Session Standards

10.1 Prompting Standards

10.2 Session Standards

11. Pull Request Review and Quality Gate Standards

11.1 General Rule

11.2 Author Responsibilities Before Opening a PR

11.3 Reviewer Responsibilities

11.4 Escalated Review

11.5 Unit Tests and Maintainability

12. Accountability Standards

13. Branching, Persistence, and Handoff Rules

14. Connector, Plugin, and Integration Guardrails

15. Controlled Rollout and Mentorship

16. Records and Retention

Appendix A — Claude Commands and Prompt Patterns Quick Reference

A1. Recommended Claude Commands

A2. New Project / Repository Setup Prompt Pattern

A3. Planning Prompt Pattern

A4. “Pick Up Where We Left Off” Prompt Pattern

A5. Debugging Prompt Pattern

A6. Documentation Prompt Example

A7. Notes on Permissions and Guardrails

Appendix B — Background Notes (Non-Procedural)

Appendix C — Recommended Minimum Contents for CLAUDE.md

Development Workflow

ATLC — Agent-Driven Testing Lifecycle

▶ ATLC Workflow Pipeline (Phases 0 – 13)

⚙ Skill Map

Reference Files

📁 AI Artifacts

📚 Context Files — Domain Knowledge Base

🔧 Correction & Learning

Agent Corrections

Team Lessons

🔗 External Integrations

ATLC Workflow

ATLC Workflow Summary