Why an AI-assisted stocktake comes first
In Level 1 we set the target: one container image and one config contract per app, deployable to Cloud Run, Azure Container Apps or AWS. Before you can containerise anything, you need a straight answer to a dull question: what do we actually run? In most legacy estates nobody has that answer in full. The wiki is from 2019, the CMDB lists servers that were turned off long ago, and the real truth is spread across hundreds of repos, Jenkins jobs and IIS boxes.
Think of this as a warehouse stocktake. AI coding tools are fast stock-counters: they can read a .csproj, a pom.xml or a Jenkinsfile in seconds. They also miscount, and sometimes they will happily invent a SKU that isn't on the shelf. So the method is: the AI drafts, the systems of record cross-check, a person signs off.
This level covers three things, in this order: guard rails, a schema-driven prompt, and a cross-check against your build servers.
Step 1: Lock the tools down before they read anything
In this phase the AI only needs to read. Give it nothing more than that.
Claude Code. Start it in plan mode, where it can read files and run read-only commands but does not edit your source. Add deny rules for secrets in .claude/settings.json:
{
"permissions": {
"deny": [
"Read(./.env)",
"Read(./.env.*)",
"Read(**/appsettings.Production.json)",
"Read(**/*.pfx)",
"Bash(cat *)"
]
}
}
claude --permission-mode plan # read-only exploration, no edits
Gotcha: a
Read(./.env)deny rule blocks the Read tool, but it won't stopcat .envrun through Bash unless you deny that form as well. Deny rules are a seatbelt, not a vault. The safer move is to scan a clean checkout with secrets already removed.
Codex CLI. Run codex --sandbox read-only. The filesystem is read-only and network access is blocked.
GitHub Copilot (VS Code). Pick the Ask or Plan agent in the chat agent picker. Both use read-only tools. Ask never writes or executes anything.
Google Antigravity. Choose the Review-driven development preset and set terminal execution to Request review, so every command waits for your approval.
Three rules apply to every tool:
- Read-only access, both to repos and to the build-server tokens you use later.
- No secrets in prompts. Never paste a connection string or API key in to "help it understand".
- Human sign-off on every entry. Nothing counts as inventory until a named person has approved it.
Step 2: Give the AI a schema, not a vibe
"Tell me about these repos" gets you prose you can't compare. A fixed schema gets you rows you can diff. Each field must point to evidence (a file path), so the reviewer can check it in seconds.
{
"app_id": "string, kebab-case",
"repo": "string",
"language": "C# | Java | Python | TypeScript | VB.NET | other",
"runtime": "e.g. .NET Framework 4.8, .NET 8, Java 11, Node 18",
"framework": "e.g. ASP.NET MVC 5, Spring Boot 2.7, Django 3.2",
"build_job": "build-server job name or null",
"hosting_server": "hostname or null",
"evidence": ["file paths that justify each field"],
"confidence": "high | medium | low",
"unknowns": ["what could not be determined"],
"reviewed_by": null
}
The prompt:
You are inventorying a legacy estate. For each top-level folder in ./repos,
produce ONE JSON object matching schema.json. Rules:
- Derive runtime from build files (*.csproj TargetFramework, pom.xml,
package.json engines, pyproject.toml), not from README text.
- Take build_job from Jenkinsfile, .teamcity/, azure-pipelines.yml or
Octopus references. Take hosting_server from deploy scripts or web.config
transforms.
- If a field is not evidenced in a file, set it to null and add it to
"unknowns". Do NOT guess.
- Leave reviewed_by as null.
Output a JSON array only.
A realistic output row:
{
"app_id": "timesheet-portal",
"repo": "timesheet-portal",
"language": "C#",
"runtime": ".NET Framework 4.7.2",
"framework": "ASP.NET MVC 5",
"build_job": "Timesheets-CI",
"hosting_server": null,
"evidence": ["src/Timesheet.Web/Timesheet.Web.csproj", "Jenkinsfile"],
"confidence": "medium",
"unknowns": ["hosting_server: deploy step calls Octopus, target not in repo"],
"reviewed_by": null
}
The explicit null plus unknowns is the most valuable part. It tells you where to look next and keeps the model honest.
Step 3: Cross-check against what the build servers say
Repos tell you what could run. Build and deploy servers tell you what does get built and shipped. Pull their lists with read-only service-account tokens held in environment variables. The AI never sees them.
# Jenkins: job names only, using the tree parameter to keep the payload small
curl -s -u "$JENKINS_USER:$JENKINS_TOKEN" \
"https://jenkins.corp/api/json?tree=jobs[name,url]" > jenkins.json
# TeamCity: every build configuration
curl -s -H "Authorization: Bearer $TC_TOKEN" -H "Accept: application/json" \
"https://teamcity.corp/app/rest/buildTypes" > teamcity.json
# Azure DevOps Server: build definitions in one project (pick the api-version your server supports)
curl -s -u ":$ADO_PAT" \
"https://tfs.corp/DefaultCollection/Finance/_apis/build/definitions?api-version=7.0" > ado.json
# Octopus: deployment targets, i.e. the servers it actually deploys to (default page size is 30)
curl -s -H "X-Octopus-ApiKey: $OCTO_KEY" \
"https://octopus.corp/api/Spaces-1/machines?take=500" > octopus.json
Then diff the lists with a small script. Use plain code here, not the AI, because this step has to be deterministic:
import json
inv = json.load(open("inventory.json"))
jobs = {j["name"] for j in json.load(open("jenkins.json"))["jobs"]}
targets = {m["Name"] for m in json.load(open("octopus.json"))["Items"]}
claimed_jobs = {a["build_job"] for a in inv if a["build_job"]}
claimed_hosts = {a["hosting_server"] for a in inv if a["hosting_server"]}
print("Jobs with no app in inventory:", sorted(jobs - claimed_jobs))
print("Apps citing a job that doesn't exist:", sorted(claimed_jobs - jobs))
print("Deploy targets no app claims:", sorted(targets - claimed_hosts))
Each result means something different:
- Job with no app: a repo you didn't clone, or a job that should have been retired.
- App citing a missing job: an AI hallucination, a renamed job, or a manual release nobody wrote down.
- Target no app claims: a server running something undocumented. Check it with the server owner and its live process list before assuming anything.
Best practice: raise each gap as a ticket. Never auto-delete an entry because it is missing from one source. "Not in Jenkins" often just means "someone builds it on their laptop".
Step 4: Human sign-off
A reviewer opens each row, clicks through the evidence paths, fixes anything wrong and sets reviewed_by to their name and the date. Commit the inventory to Git so every correction has a diff and an author. A row with reviewed_by: null is still a draft.
Key takeaways
- Set the guard rails before scanning: read-only modes, read-only tokens, no secrets in prompts, a clean checkout.
- A fixed JSON schema with
evidence,confidenceandunknownsturns AI output into rows you can check and diff. - Tell the model to return
nullrather than guess. The unknowns list is your to-do list. - Cross-check with deterministic scripts against Jenkins, TeamCity, Azure DevOps Server and Octopus. Each mismatch is a ticket, not an automatic deletion.
- Nothing is inventory until a named person signs it off.