Amazon Q Developer: Custom Context Packs for Private Monorepos

context-packs/
  billing/
    PACK.json          # manifest + content hash
    adr-summaries.md   # 1 paragraph per ADR
    public-api.md      # exported symbols from package.json exports
    forbidden.md       # banned libs and patterns
    ownership.md       # CODEOWNERS excerpt
    contracts/         # OpenAPI snippets for billing APIs

{
  "name": "billing",
  "packages": ["@acme/billing", "@acme/billing-client"],
  "maxTokens": 12000,
  "negatives": ["moment", "request", "aws-sdk@2"],
  "sha": "content-hash-of-all-files"
}

// scripts/build-context-pack.ts
import { readFileSync, writeFileSync } from "fs";
import { createHash } from "crypto";

export function buildPublicApi(pkgRoot: string): string {
  const pkg = JSON.parse(readFileSync(`${pkgRoot}/package.json`, "utf8"));
  const exports = pkg.exports ?? { ".": pkg.main };
  // ✅ Only document real export paths
  return Object.keys(exports)
    .map((k) => `- \`${pkg.name}${k === "." ? "" : "/" + k.replace(/^\.\//, "")}\``)
    .join("\n");
}

export function writePack(dir: string, files: Record<string, string>) {
  const body = Object.entries(files)
    .sort(([a], [b]) => a.localeCompare(b))
    .map(([k, v]) => `# ${k}\n\n${v}`)
    .join("\n\n");
  const sha = createHash("sha256").update(body).digest("hex").slice(0, 16);
  writeFileSync(`${dir}/PACK.md`, body);
  writeFileSync(`${dir}/PACK.json`, JSON.stringify({ sha, bytes: body.length }, null, 2));
}

# ❌ Wrong: zip the entire monorepo into Q context
tar czf q-context.tgz packages/ apps/ node_modules/

## Forbidden in billing pack

- ❌ `moment` / `moment-timezone` — use `luxon`
- ❌ `aws-sdk` v2 — use `@aws-sdk/*` v3 modular clients
- ❌ Deep imports from `@acme/billing/src/**` — public barrels only
- ✅ Prefer `@acme/billing-client` for cross-service calls

# .amazonq/context.yml (illustrative)
include:
  - context-packs/**/*.md
  - docs/adr/**/*.md
exclude:
  - "**/.env*"
  - "**/secrets/**"
  - "**/fixtures/pii/**"
max_file_bytes: 64000

# CI: rebuild packs and fail if committed hash mismatches
- run: pnpm tsx scripts/build-context-pack.ts
- run: git diff --exit-code context-packs/