Agent Engineering HandbookGitHub

Idea 11 of 19 The nineteen ideas

Treat newcomer questions as a signal for onboarding gaps (Theo's dumb-questions practice)

On this page

Newcomer questions reveal unclear project guidance

Theo describes asking new teammates to ask at least one dumb question per day on his teams. Their questions exposed what was unclear to people encountering the codebase for the first time. He values that perspective because a person is only a beginner in a particular codebase once.

Answer newcomer questions and fix their causes

Record newcomer questions without blame, answer the person, and periodically review what made each question necessary. Address the underlying gap with clearer naming, a missing document, a lint rule, or a steering-file entry. Treat an agent's repeated confusion as another signal to inspect the same kind of onboarding gap.

Repeated confusion points to missing project guidance

Use this when onboarding engineers reveals assumptions that established teammates no longer notice in the codebase. It also fits repeated agent confusion where the project has failed to make needed knowledge clear. Collecting questions without addressing their causes does not by itself repair the gaps those questions reveal.

Make questions safe without requiring daily quotas

This is a cultural practice Theo describes for his own teams, rather than a rule adopted here. No daily quota is required, and the practice depends on people feeling safe enough to ask. The idea still applies when questions lead to answers and repairs, rather than becoming a requirement to produce questions.

Watch at 11:14 · Home · Agent Engineering Handbook, September 9, 2026