Codebase Briefing — Rules, Contracts And Traps

Coding agents often cause damage by guessing how a repository works. They lack context on where modules live, what the house coding style is, and which structural traps to avoid. This skill prevents expensive mistakes by generating a verified briefing pack that informs an agent before it writes a single line of code.

What it does

• Module Mapping generates a high-level view of entry points and package boundaries to prevent misplaced logic.
• Convention Detection identifies actual house rules for naming and structure, backed by repository evidence.
• Decision Tracking extracts explicit architecture decisions (ADRs) so agents don't ignore established technical choices.
• Contract Analysis surfaces public APIs and exports to ensure changes don't break downstream dependencies.
• Trap Identification warns about circular dependencies and layering violations that an agent might otherwise trigger.
• Command Discovery lists the exact build, test, and lint scripts required for the specific stack.

How it works

1. Frame the scope by defining if the briefing covers the whole repository, a specific directory, or a single file for validation.
2. Collect repository state by reading README.md, CONTRIBUTING.md, and architectural docs while preserving existing git changes.
3. Execute analysis using agent-context or manual inspection to extract the module map, detected rules, and structural diagnostics.
4. Assemble the briefing into a structured document that separates human-written rules from tool-inferred heuristics.

Frameworks & tools

This skill is stack-agnostic but optimized for repositories using git. It utilizes the ai-agent-context CLI for deep structural analysis and degrades to standard shell commands like find and grep when specialized tools are unavailable.

Why this beats prompting it yourself

Generic prompts result in agents hallucinating file paths or making assumptions based on public boilerplate rather than your team's specific practices. This skill enforces a read-only analysis contract that extracts evidence-based rules, ensuring the agent operates on facts instead of guesses.

Use cases

• Agent Onboarding to prepare an AI for work in a large, unfamiliar monorepo.
• Rule Verification to check if a proposed file or PR follows existing house conventions.
• Pre-flight Audits to identify architectural traps before starting a complex refactor.
• Legacy Knowledge Recovery to surface forgotten ADRs and public API boundaries.

Known limitations

Read-only analysis that never writes or modifies code. Heuristic confidence varies; explicit documentation always outranks tool inference. Analysis depth is limited by the moduleDepth configuration.