Skill in 《Harness Step 1 — Create AGENTS.md & Knowledge Base》

Skill.md

Harness Step 1 — Create AGENTS.md & Knowledge Base

The core problem with Claude Code on real projects: every new session starts cold. The agent has no idea what the project is, how it's structured, or what the rules are. You end up re-explaining the same things across dozens of sessions. This skill fixes that at the source — scan the codebase once, generate structured knowledge files, and every future session orients in under 30 seconds without your help.

What Gets Generated

project-root/
├── AGENTS.md                    ← agent's orientation file, 80-120 lines
└── docs/
    ├── ARCHITECTURE.md          ← module map, dependency rules, data flows
    ├── CONVENTIONS.md           ← naming patterns, file organization
    ├── TECH_DECISIONS.md        ← why each framework/library was chosen
    ├── QUALITY.md               ← Definition of Done, code review checklist
    └── exec-plans/
        ├── active/              ← in-progress work
        ├── backlog.md           ← planned but not yet scheduled
        └── tech-debt-tracker.md ← known quality issues

Design Principles

• AGENTS.md is the table of contents, docs/ is the book: agents use AGENTS.md to orient, docs/ to understand
• Inferred ≠ invented: anything that can't be confirmed from the codebase is marked "TODO: confirm" — never fabricated
• Stack-agnostic: Python, Node.js, Go, Rust; monolith, microservices, monorepo — all work

Supported Use Cases

• Adding agent support to an existing project for the first time
• Onboarding to an unfamiliar codebase (let the agent read it first, then work with you)
• Refreshing agent context after a major refactor
• Any situation where you want Claude Code to stop asking "what is this project?"

How to Use

1. Open Claude Code in your project root
2. Say "add agent support" or "create AGENTS.md" or "start harness engineering"
3. The skill scans 2–3 directory levels, dependency files, and existing docs
4. All files are generated; the skill lists what needs human confirmation
5. Run harness-step2-fill-docs next to deep-fill docs/ with content from the actual code

Limitations

The skill reads files only — it can't observe runtime behavior (API response shapes, DB contents). TECH_DECISIONS.md often needs human input for historical context: the code shows what was chosen, but not why.