code-research（代码研究）

Code Research

Methodology for researching code patterns, architecture decisions, and implementation approaches. This skill governs *how to find answers* and *which sources to trust* — ensuring research always prioritizes industry best practice, elegant idiomatic implementations, and authoritative sources.

Based on standards bodies (IETF, W3C, ECMA, ISO, POSIX), Big Tech engineering publications (Google, Stripe, Cloudflare, Meta, AWS, Netflix, Discord), recognized expert writings (Fowler, Beck, Hickey, Kleppmann, Pike, Cantrill), and well-governed OSS reference implementations.

Scope boundary: This skill covers research *methodology* — where to look, what to trust, how to report findings. For domain-specific guidance: - API contract decisions and HTTP semantics → API Design skill (/api-design) - Rust implementation patterns → Rust skill (/rust) - TypeScript/React patterns → TypeScript skill (/typescript) - Security posture and threat models → Web Security skill (/web-security)

1. Source Authority Hierarchy

Rank sources by authority. Higher tiers override lower tiers when they conflict.

Tier 1 — Standards and specifications

The ground truth. Always check here first when a standard exists.

Tier 2 — Big Tech engineering (on topics where they lead)

Trust a company's engineering publications *only on topics where they are a recognized leader*. A company's blog post outside their domain of expertise is Tier 5.

Tier 3 — Recognized expert figures

Individuals with sustained, peer-recognized contributions. Their writings carry authority on their specific domains.

Tier 4 — Well-maintained OSS projects

Reference implementations with strong governance. Code as documentation of best practice.

• Criteria: active maintenance, multiple contributors, clear governance, production use at scale
• Examples: tokio (async Rust), React (UI), PostgreSQL (relational DB), Linux kernel (OS), Axum (web framework), Go standard library

Tier 5 — Community content

Useful for discovery and initial orientation. Never rely on as sole authority.

• Conference talks, blog posts, tutorials, Stack Overflow answers, Reddit discussions, dev.to articles, Medium posts
• Always verify claims from Tier 5 sources against higher-tier sources before adopting

2. Evaluating Sources

Recency

• Check version alignment: Is the advice for the current major version of the tool/language? Post-React 18 patterns differ significantly from pre-hooks era. Rust 2021 edition changed trait resolution.
• Check standard status: Is the RFC ratified or still a draft? Draft standards may change. Note the distinction explicitly (e.g., "OAuth 2.1 draft" vs "RFC 9700").
• Deprecation signals: Archived repos, "this approach is no longer recommended" notices, superseded RFCs.

Context match

• Production scale vs hobby project: A pattern that works for a personal blog may fail at 10k RPS. Match the source's deployment context to yours.
• Team size: Patterns designed for 500-engineer organizations may have different trade-offs for a 3-person team — but smaller teams still need correct, robust implementations. Team size affects *what* you build, not *how well* you build it.
• Language/ecosystem: A pattern idiomatic in Go (explicit error returns) should not be cargo-culted into Rust (Result types) or TypeScript (exceptions).

Conflict resolution

When authoritative sources disagree:

1. Trace to Tier 1: If a standard exists, it wins
2. Compare production evidence: Which approach is proven at scale? By how many independent organizations?
3. Check recency: The more recent source may reflect lessons learned
4. Note the conflict explicitly in findings — don't silently pick a winner
5. Present both positions with their trade-offs and let the planner/user decide

3. Research Process

Search strategy

Follow this order. Stop when you have sufficient authoritative coverage.

1. Official docs and specs — language reference, framework docs, relevant RFCs
2. Engineering blogs from domain leaders — Tier 2 companies on their specialty topics
3. Expert writings — Tier 3 figures on their domains
4. Reference implementations — Tier 4 OSS projects, read the actual code
5. Community content — Tier 5 for discovery, patterns you haven't considered

Cross-reference requirement

Before adopting a pattern or recommendation:

• Verify against at least two authoritative sources (Tier 1-3)
• If only Tier 5 sources exist, flag this explicitly in findings
• If a single authoritative source exists with no corroboration, note this — it may still be correct, but confidence is lower

Web search guidance

• Start with specific queries: "RFC 9457" problem details not api error handling
• Include version numbers: react 19 server components not react server components
• Prefer primary sources in results: site:datatracker.ietf.org, site:stripe.com/docs
• When evaluating blog posts, check the author's credentials and the publication date

4. Quality Standards

When researching implementations, evaluate every candidate pattern against these quality dimensions — in priority order:

Standards compliance

The best solution conforms to established standards. A technically elegant approach that violates HTTP semantics, language specifications, or protocol requirements is not a good solution. Standards exist because they encode hard-won consensus about interoperability and correctness.

Reliability and robustness

Prefer patterns that handle failure gracefully, degrade predictably, and have been battle-tested under adversarial conditions. Evaluate:

• Error handling completeness — does the pattern account for all failure modes, not just the happy path?
• Edge case behavior — how does it handle empty inputs, concurrent access, network partitions, clock skew?
• Recovery characteristics — does it fail fast, fail safe, or fail silently? Fail-fast with clear diagnostics is preferred.
• Observability — can you tell what went wrong from logs and metrics alone, without attaching a debugger?

Elegance and coherence

The best solution is the one that fully and properly solves the problem with nothing extraneous and nothing missing. Evaluate:

• Idiomatic to the language/framework — not translated from another ecosystem. Go error handling should not look like Java exceptions. Rust should use ? and Result, not boolean flags.
• No unnecessary moving parts — fewer allocations, fewer indirections, fewer configuration knobs. But "fewer" never means "skip what's needed." Three lines of clear code beats a clever one-liner, but don't remove structure that protects correctness.
• Conceptual clarity — can a new team member understand the pattern without a 30-minute explanation? If not, the complexity must be justified by the problem's inherent complexity.
• Composability — does the pattern compose well with the rest of the system, or does it require special plumbing everywhere it's used?

Industrial-grade quality

The pattern should be production-ready — not a prototype that "works on my machine":

• Proven at scale — used in production by organizations that have validated the approach under load, failure, and maintenance pressure
• Maintainable — easy to modify, extend, and debug six months from now by someone who didn't write it
• Testable — can be unit tested, integration tested, and property tested without elaborate mocking
• Operationally sound — supports deployment, rollback, monitoring, and incident response

Language-specific idiom sources

Defer to the language-specific skill for detailed idiom guidance:

• Rust idioms → Rust skill (/rust)
• TypeScript/React idioms → TypeScript skill (/typescript)
• For languages without a dedicated skill, refer to the language's official style guide and Tier 4 reference implementations

5. Reporting Findings

Attribution format

When writing research.md or reporting findings, attribute sources with:

• Tier level — so the reader knows the authority weight
• Author or organization — who said this
• Date or version — when, to assess recency
• URL — when available, for verification

Example: (Tier 1, IETF RFC 9457, 2023) or (Tier 2, Stripe engineering blog, 2024) or (Tier 5, Stack Overflow answer, 2022 — verify against primary source)

Confidence signals

• Flag when only lower-tier sources exist — "No Tier 1-3 sources found; recommendation is based on community consensus only"
• Flag conflicts explicitly — "Google AIP recommends X; Stripe practice differs with Y. Trade-off:..."
• Flag draft standards — "Based on OAuth 2.1 draft (not yet ratified); may change"
• Flag recency concerns — "Source predates React 19; patterns may be outdated"

Structure

Write findings to research.md with sections: Summary, Stack, Existing patterns, Integration points, Gotchas, Testing, Open questions. Add a ## Sources section at the end with tiered attribution for all referenced materials.

6. Anti-patterns