Module 19 · Lesson 03

Technical Handoff Documentation — Architecture, Credentials, and the Engineering Runbook

Reading time: 18 minutes Track: Yungsten Tech Employee Curriculum · Implementation Engineering

Why technical handoffs are different from functional handoffs

Module 15 covers the functional handoff: the runbook a COO reads at 9pm when something breaks. That document is written for a non-technical operator. It covers what the agent does, how to trigger it, and what to do when common things go wrong.

The technical handoff serves a different reader: the person who will eventually need to modify, debug, or rebuild the system. This might be a client-side engineer, a future Yungsten engineer taking over the engagement, or the client's IT team when the original operator leaves.

Without technical handoff documentation, the system is brittle. It works until something breaks at a layer the functional runbook doesn't cover, and the people left with it don't have enough to diagnose the problem.

The four technical handoff artifacts

Artifact 1: The architecture document

One page that covers the full system topology:

# [Agent Name] — System Architecture
Last updated: [date]  Engineer: [name]

## Overview
[2-3 sentences describing what this system does at an architectural level]

## Components
| Component | Type | Version | Location | Purpose |
|---|---|---|---|---|
| Claude Desktop | Application | [version] | Client machine | Agent host |
| [MCP Server 1] | npm package | [version pinned] | [install path] | [what it connects to] |
| [MCP Server 2] | npm package | [version pinned] | [install path] | [what it connects to] |

## Data flow
[Input source] → [How it enters] → Claude Desktop → [Output destination]

## External dependencies
| Service | Used by | Auth method | Owner |
|---|---|---|---|
| [API/service name] | [MCP server name] | [API key/OAuth/etc] | [who owns this credential] |

## Known limitations
- [List any design constraints or known failure conditions]

Artifact 2: The credential map

A document (stored separately from version control, in the client's secrets manager or a secured location) that covers every credential the system uses:

# Credential Map — [Client Name] AI Stack

## [Agent Name]
| Credential | Service | Type | Storage location | Owner | Rotation schedule |
|---|---|---|---|---|---|
| GDRIVE_CLIENT_ID | Google Drive MCP | OAuth client ID | macOS Keychain | [name] | No rotation needed |
| GDRIVE_CLIENT_SECRET | Google Drive MCP | OAuth secret | macOS Keychain | [name] | Rotate if exposed |
| NOTION_API_KEY | Notion MCP | Bearer token | 1Password "AI Stack" | [name] | Annual or on staff change |

## Rotation procedure
When rotating [credential type]:
1. Generate new credential at [service admin URL]
2. Update in [storage location] on [whose machine(s)]
3. Restart Claude Desktop to pick up the new value
4. Verify by running: [test command or agent test case]
5. Update "last rotated" date in this document

Artifact 3: The debugging playbook

Distinct from the functional runbook — this covers how an engineer would debug the system, not just how an operator would handle common failures:

# Debugging Playbook — [Agent Name]

## Checking MCP server status
1. Open Terminal
2. Run: claude_desktop_config location: [path]
3. For each mcpServer, verify connectivity:
   - filesystem: ls [configured path] — should return files
   - [other servers]: [test command]

## Reading Claude Desktop logs
macOS: ~/Library/Logs/Claude/
Look for: mcp-server-*.log (one per server), claude.log

## Common failure patterns

### Agent gives generic responses instead of using tools
Likely cause: MCP server not loaded. Check:
- claude_desktop_config.json syntax (validate with: python3 -m json.tool config.json)
- Whether Claude Desktop was restarted after last config change
- Whether the npm package is installed (npx [package]@[version] --version)

### Tool returns empty results
Check: Does the path/connection actually have data?
- filesystem: Does the configured directory exist and have files Claude can read?
- gdrive: Is the OAuth token still valid? (Try revoking and re-authing)

### Agent ignores constraints from system prompt
Check: Is the system prompt actually set in the Claude Project, not just in a conversation?
System prompts set in conversations don't persist. Projects are persistent.

Artifact 4: The upgrade checklist

A documented procedure for upgrading any component of the stack:

# Upgrade Procedure — [Agent Name]

## Before upgrading any component
- [ ] Take a snapshot of current claude_desktop_config.json
- [ ] Note current versions of all MCP servers
- [ ] Notify [client contact] that a maintenance window is scheduled
- [ ] Ensure current test cases are documented and passing

## MCP server upgrade procedure
1. Research the changelog: npm show [package] changelog or GitHub releases
2. Test in dev environment first (minimum 1 day of normal use)
3. Update version pin in production config
4. Restart Claude Desktop, run all test cases
5. Update architecture document with new version
6. If any test case fails, roll back to previous version pin

## System prompt version procedure
System prompts are versioned in /system-prompts/[agent-name].md in the engagement repo.
- Append to the file with a version header: ## v[N] — [date] — [description of change]
- Never overwrite previous versions
- Test the new version against all five standard test cases before deploying to client

Storing and handing off technical documentation

Technical documentation lives in the engagement repo, not the client's wiki (which is written for non-technical operators). At engagement handoff:

• The engagement repo is transferred to a location the client's technical contact can access
• The credential map is stored in the client's secrets manager with access granted to their designated technical owner
• A 30-minute technical handoff call walks the client's technical contact through all four artifacts
• The client technical contact demonstrates they can locate and interpret each artifact independently

The standard: a competent engineer who has never seen this system before could, using only these four documents, diagnose a failure and restore the system to operation within two hours.