specification, repository access, connector bindings, and a trigger configuration.
Architecture Decisions
- Ephemeral Execution: Every routine run spins up a fresh environment. There is no state carried over between runs. This design ensures security and isolation but requires prompts to be idempotent. If a routine runs twice, the second run must handle the case where the first run already completed the work.
- Connector Injection: Connectors (Slack, Linear, MCP servers) are attached at runtime. This allows the same routine to be reused across environments by swapping connector configurations without modifying the prompt.
- Trigger Composition: Routines support multiple triggers. A common pattern is combining a scheduled trigger for housekeeping with an API trigger for on-demand execution. This maximizes utility while staying within daily run limits.
Implementation Workflow
The following example demonstrates a production-grade routine for automated security triage. This routine monitors pull requests, scans for vulnerabilities, and reports findings without human intervention.
1. Define the Routine Specification
Instead of ad-hoc CLI commands, define routines using a structured configuration. This approach improves version control and reproducibility.
# routine-config.yaml
name: security-triage-pr
description: Scans PRs for security risks and reports to Linear
repositories:
- github:acme-platform/core-api
connectors:
- slack:security-alerts
- linear:security-board
triggers:
- type: github
events: [pull_request.opened, pull_request.synchronize]
branches: [main, release/*]
prompt: |
You are the security gatekeeper for this repository.
Analyze the diff provided in the context for the following:
1. Hardcoded secrets or credentials.
2. Weak cryptographic implementations.
3. Exposed endpoints lacking authentication.
4. SQL injection vulnerabilities.
For each finding:
- Classify severity: CRITICAL, HIGH, MEDIUM, LOW.
- If CRITICAL or HIGH:
- Create a Linear ticket in the 'Security' project.
- Set priority to 'High'.
- Tag the PR author in the ticket description.
- If MEDIUM or LOW:
- Post a summary to #security-alerts on Slack.
- Include a link to the PR and the specific file/line.
Do not modify code. Only report findings.
If no issues are found, post a '✅ Security Clear' message to Slack.
2. Create via CLI
Use the CLI to register the routine. The configuration is validated, and the routine is synced across all surfaces (Web, Desktop, CLI).
claude routines create \
--config ./routine-config.yaml \
--name security-triage-pr
3. Invoke via API Trigger
For on-demand execution, use the API endpoint. This is useful for integrating routines into deployment scripts or external monitoring tools.
curl -X POST https://api.anthropic.com/v1/routines/exec \
-H "Authorization: Bearer rc_live_..." \
-H "Content-Type: application/json" \
-d '{
"routine_id": "sec_triage_001",
"payload": {
"env": "staging",
"version": "2.4.0",
"dry_run": false
}
}'
4. Dry Run and Iteration
Always execute a manual dry run before enabling scheduled or event triggers. Inspect the session logs to verify that the prompt produces the expected output and that connectors are functioning. Refine the prompt based on false positives or missed detections.
Pitfall Guide
Routines introduce new failure modes distinct from traditional scripts. The following pitfalls are common in production deployments.
-
The "God Prompt" Trap
- Explanation: Attempting to handle too many distinct tasks in a single routine leads to context window exhaustion and unreliable behavior.
- Fix: Decompose complex workflows into focused routines. A routine should do one thing well. If a routine needs to triage issues and update docs, split them into two routines triggered by the same event.
-
State Assumption Errors
- Explanation: Assuming the routine remembers previous runs. Since sessions are ephemeral, a routine cannot recall that it already processed an issue unless that state is explicitly checked in the repository or via API.
- Fix: Design idempotent prompts. Include logic to check for existing labels, comments, or tickets before creating new ones. Example: "Check if issue #123 already has the 'triaged' label before proceeding."
-
Trigger Storms
- Explanation: GitHub events can fire rapidly (e.g., multiple pushes in quick succession), exhausting daily run limits or causing duplicate work.
- Fix: Use branch filters and event deduplication in the prompt. For scheduled routines, add a "last run" check to prevent redundant execution. Monitor run counts closely during initial deployment.
-
Safety Blind Spots
- Explanation: Routines run autonomously with full tool access. A misconfigured routine can delete branches, post incorrect messages, or modify production configs.
- Fix: Apply the principle of least privilege. Use API triggers for dangerous operations rather than schedules. Include explicit constraints in the prompt: "Do not merge PRs. Do not delete branches. Only create comments."
-
Limit Exhaustion
- Explanation: Hitting daily run limits (Pro: 5, Max: 15, Team/Enterprise: 25) due to too many small routines.
- Fix: Consolidate routines. Combine related tasks into a single routine that performs multiple steps. For example, a "Weekly Health Check" routine can handle dependency reports, stale branch cleanup, and changelog generation in one session.
-
Connector Auth Rot
- Explanation: Routine failures due to expired tokens or revoked permissions for Slack, Linear, or MCP servers.
- Fix: Implement monitoring for routine failures. Set up alerts for authentication errors. Rotate tokens proactively and verify connector status during dry runs.
-
Output Noise
- Explanation: Routines posting excessive updates to Slack or email, leading to alert fatigue and muted channels.
- Fix: Implement summarization thresholds. Only post when significant findings exist. Use structured formatting and include links for details rather than dumping raw data. Example: "Post summary only if >3 issues found; otherwise log silently."
Production Bundle
Action Checklist
Decision Matrix
| Scenario | Recommended Approach | Why | Cost Impact |
|---|
| Ad-hoc debugging | Interactive Session | Requires human intuition and real-time feedback. | Low (Usage-based) |
| Nightly cleanup | Scheduled Routine | Repetitive, async, no human judgment needed. | Efficient (1 run/day) |
| PR review feedback | GitHub Trigger Routine | Fast, consistent, reduces reviewer fatigue. | Efficient (Per PR) |
| Complex multi-step workflow | Consolidated Routine | Reduces limit usage; maintains context across steps. | Efficient (1 run vs multiple) |
| Safety-critical operation | API Trigger + Human Gate | Prevents autonomous errors; requires explicit invocation. | Controlled (Manual trigger) |
| Documentation updates | GitHub Trigger Routine | Ensures docs stay in sync with code changes. | Efficient (Per merge) |
Configuration Template
Use this template as a starting point for new routines. Customize the prompt, connectors, and triggers based on your requirements.
# routine-template.yaml
name: example-routine
description: Template for production routines
repositories:
- github:org/repo-name
connectors:
- slack:engineering-updates
- linear:project-board
triggers:
- type: schedule
cron: "0 9 * * 1" # Monday 9am
- type: api
# Optional: Enable API trigger for on-demand execution
prompt: |
You are an autonomous engineering assistant.
Context:
- Repository: {{repository}}
- Trigger: {{trigger_type}}
Task:
1. Analyze the current state of the repository.
2. Perform the following actions:
- Action A: Description of action.
- Action B: Description of action.
3. Output format:
- Summary of findings.
- Links to created tickets or comments.
Constraints:
- Do not modify production configurations.
- Do not merge pull requests.
- If uncertain, log a warning and stop.
Idempotency:
- Check for existing results before creating new items.
- Skip actions that have already been completed.
Quick Start Guide
- Install CLI: Ensure Claude Code CLI is installed and authenticated. Run
claude --version to verify.
- Create Routine: Use
claude routines create with a configuration file or interactive prompts. Define the prompt, repositories, and connectors.
- Test Execution: Run
claude routines run <routine-name> to execute a dry run. Inspect the output and logs.
- Enable Triggers: Add triggers via the web interface or CLI. For GitHub events, ensure the repository is connected. For schedules, verify the cron expression.
- Monitor: Check the routine dashboard for execution status. Review logs for errors and refine the prompt as needed.
Routines represent a paradigm shift in how AI integrates into engineering workflows. By treating routines as autonomous agents rather than simple scripts, teams can build resilient, self-maintaining systems that reduce toil and improve code quality. The key to success lies in precise prompt specifications, careful trigger management, and continuous monitoring. Start with a single routine, validate its reliability, and expand gradually to maximize impact while minimizing risk.